home *** CD-ROM | disk | FTP | other *** search
/ SysOp's Arsenal / SysOp's Arsenal 1 (Arsenal Computer).ISO / rip / ripscrip.doc < prev    next >
Text File  |  1994-08-15  |  280KB  |  6,287 lines
  1.  
  2.  
  3.  
  4.  
  5.              ------------------------------------------
  6.               RIPscrip Graphics Protocol Specification
  7.                      "Remote Imaging Protocol"
  8.  
  9.                       Copyright (c) 1992-1993
  10.                   TeleGrafix Communications, Inc.
  11.                         All Rights Reserved
  12.  
  13.                             Revision 1.54
  14.  
  15.                            July 19th, 1993
  16.              ------------------------------------------
  17.  
  18.  
  19.  
  20.  
  21.  
  22. =====================================================================
  23. ==                           INTRODUCTION                          ==
  24. =====================================================================
  25.  
  26. As system operators of many bulletin board systems, we've often
  27. wished for some form of Graphical User Interface for our boards. Like
  28. most Sysops, we've come across many solutions.  But they all seemed
  29. to fall short in one way or another:  inadequate for THIS system,
  30. incomplete, difficult to implement, too complex, or lacking in
  31. graphics development tools.  In short, we became frustrated.
  32.  
  33. So, we decided to write our own Graphical Script Language.
  34.  
  35. RIPscrip stands for "Remote Imaging Protocol Script" language.  This
  36. graphical language is our answer to the graphics needs of the BBS
  37. community and has serious tools for implementation and practical use.
  38.  
  39. For more information on RIPaint, RIPdraw, RIPterm or RIPscrip development
  40. tools (RIP2C, RIP2PAS, etc), contact:
  41.  
  42.      TeleGrafix Communications, Inc.
  43.      16458 Bolsa Chica #15
  44.      Huntington Beach, CA  92649
  45.  
  46.      VOICE: (714) 379-2131
  47.      FAX  : (714) 379-2132
  48.      DATA : (714) 379-2133 (ArenaBBS: The Major BBS...32 lines)
  49.  
  50.  
  51.  
  52.  
  53. =====================================================================
  54. ==                    REVISION HISTORY NOTATION                    ==
  55. =====================================================================
  56.  
  57. This document is a historical document.  Periodically throughout the  > v1.54
  58. text are things that were added to the specification at specific      > v1.54
  59. revisions.  These additions/changes can be easily pinpointed by       > v1.54
  60. looking for notation symbols in the right margin of the document.  If > v1.54
  61. you notice to the right of this paragraph are the symbols "> 1.54"    > v1.54
  62. which indicate that this section was added in the v1.54 revision of   > v1.54
  63. the RIPscrip Protocol Specification.  This notational convenience was > v1.54
  64. added to make quick determination of new changes fast and easy.       > v1.54
  65.  
  66.  
  67.  
  68.  
  69. =====================================================================
  70. ==                   USE OF THE RIPscrip LANGUAGE                  ==
  71. =====================================================================
  72.  
  73. The RIPscrip language is made publicly available and is freely
  74. licensed by TeleGrafix Communications, Inc.  By freely licensed, we
  75. mean that the language can be used in the creation of other products.
  76. It does not mean that RIPscrip is public domain. TeleGrafix maintains
  77. the copyright of the RIPscrip language.
  78.  
  79. RIPscrip, RIPaint, RIPdraw, and RIPterm are trademarks of TeleGrafix
  80. Communications, Inc.  If you make a product that uses RIPscrip, you
  81. must state in your program's "About Box" and documentation that this
  82. product uses RIPscrip and the trademark statement.  You may not use
  83. RIPterm, RIPaint, RIPdraw, or RIPterm in the name of your product.
  84.  
  85. If you have any questions regarding these issues, contact TeleGrafix
  86. Communications, Inc. at 714/379-2131.
  87.  
  88.  
  89.  
  90.  
  91. =====================================================================
  92. ==                            DEFINITION                           ==
  93. =====================================================================
  94.  
  95. RIPscrip is a text based Script language for displaying online
  96. graphics.  The script language conforms to 7-bit ASCII, avoiding the
  97. use of Extended ASCII characters.  This allows transmission over X.25
  98. networks and other carriers that do not support full 8-bit binary
  99. transfers easily.  RIPscrip allows RIPscrip graphical statements to
  100. be mixed with printable ASCII text and [de facto standard]
  101. ANSI/VT-100 directives.  RIPscrip can dynamically determine what is
  102. graphics and what is text and display them appropriately in separate
  103. windows (a graphics window and a text window).  And if you must have
  104. your own proprietary commands, RIPscrip has room for that too.
  105.  
  106.  
  107.  
  108.  
  109. =====================================================================
  110. ==                     HOW DOES RIPscrip WORK?                     ==
  111. =====================================================================
  112.  
  113. RIPscrip uses a flexible, and very efficient script language for its
  114. graphical statements.  Its efficiency stems from its compactness and
  115. developmental planning.  It is entirely Object Oriented instead of
  116. Raster Oriented for efficient transmission of data and powerful
  117. editing capabilities (using RIPaint for example).  The language is
  118. open ended enough so that literally trillions of different graphics
  119. commands can be implemented as needed.  RIPscrip is not a proprietary
  120. protocol standard and is open to suggestion from the rest of the
  121. world.
  122.  
  123. Earlier Graphical Script Languages (Avatar and Skypix among others),
  124. utilize special command characters to indicate which graphics command
  125. is to be executed.  This precludes their use on systems that are
  126. limited to ASCII printable text.  Traditional script languages use
  127. English words to accomplish things (eg, "BOX 0,0 100,50").  This kind
  128. of thing is incredibly bulky, especially when you consider that
  129. pictures are usually not simple things, but comprised of hundreds or
  130. thousands of individual graphical operations (eg, line, circles,
  131. fills, text, etc.).  With this in mind, a human-readable script
  132. language was completely inappropriate for the relatively limited
  133. bandwidth of conventional modems.
  134.  
  135. So, one of our main strategies for this language was to make it as
  136. efficient as possible without going completely binary.  This allows
  137. the immediate installation of the protocol onto any ASCII text-based
  138. host system -- because the language consists entirely of ASCII
  139. printable characters.  We justify the unreadability of the language
  140. by pointing out the limitations of today's modems and phone lines --
  141. the language must be compact.
  142.  
  143.  
  144.  
  145.  
  146. =====================================================================
  147. ==              RIPscrip PROTOCOL - GENERAL STRUCTURE              ==
  148. =====================================================================
  149.  
  150. This document describes RIPscrip commands up through version 1.54
  151. of the RIPscrip Protocol Specification.
  152.  
  153. RIPscrip is organized into 10 levels of graphical commands (low
  154. Level-0 to high Level-9).  Level-0 commands are the building blocks
  155. of RIPscrip.  The basic graphics primitives of the system are all
  156. Level-0, including the commands Line, Rectangle, Circle, Color, Font,
  157. etc.  Each level of RIPscrip gets progressively higher-level in
  158. concept.  For example, Level-1 commands use Mouse Regions, Icons, and
  159. Formatted Text Regions.
  160.  
  161. The basic syntax rules are as follows:
  162.  
  163. 1.  A RIPscrip command line starts at the beginning of a line of
  164.     text.  A RIPscrip command line moved to the middle of a line of
  165.     text is treated as literal text. This prevents people inserting
  166.     mischievous things in teleconference messages, or similar pranks.
  167.     The only exceptions to this rule is stated below under item 6,
  168.     "continuation of long lines", and item 12 "alternate RIPscrip
  169.     starting sequences".
  170.  
  171. 2.  A RIPscrip command line begins with an exclamation mark (!).
  172.  
  173. 3.  Every RIPscrip command is preceded by the universal RIPscrip
  174.     delimiter, vertical-bar (|)
  175.  
  176. 4.  Individual RIPscrip commands may be combined on the same line
  177.     providing they are separated by the vertical bar delimiter.
  178.  
  179. 5.  RIPscrip commands or command lines may be split across multiple
  180.     lines with a backslash (\) just before each split.  This helps
  181.     RIPscrip commands conform to right margins and escape word
  182.     wrapping.
  183.  
  184.           An example:
  185.  
  186.                !|c02|L02030405|P0901020102010201020102\
  187.                0102010201020102
  188.  
  189. 6.  RIPscrip must allow for normal text to be intermixed with
  190.     RIPscrip commands.  If unrecognized text appears after a RIPscrip
  191.     command, on the same line, the text is ignored (the command is
  192.     not ignored).  A line that does not begin with "!|" is considered
  193.     raw text and is routed to the TTY text window (see "8" below).
  194.  
  195. 7.  RIPscrip makes provisions for a Graphical Window and a Text
  196.     Window.  The Graphical Window is where all RIPscrip graphics
  197.     appear.  The Text Window is where raw text appears.  Raw Text
  198.     includes ANSI color and cursor movement codes (a subset of VT-100
  199.     terminal emulation).
  200.  
  201. 8.  The vertical bar (|) of a RIPscrip command can be followed by a
  202.     level number.  If the 1st character after (|) is a numeric digit
  203.     (1-9), then that's the RIPscrip Command Level.  If the very 1st
  204.     character is NOT a digit 1-9, then it is the command type
  205.     character and the command is a Level-0 command.  If the 1st
  206.     character is a digit 1-9, and the second character is also a
  207.     digit, then that defines a sub-level of a RIPscrip level.  For
  208.     example:
  209.  
  210.           !|L     RIPscrip Level-0 Command "L"
  211.          !|1L     RIPscrip Level-1 Command "L"
  212.         !|15L     RIPscrip Level-1, sub-level 5 Command "L"
  213.  
  214.     Each of the above examples are unique commands not to be confused
  215.     with each other.  You may continue the sub-levels up to a maximum
  216.     level of 9 (e.g., !|123456789<cmd>").
  217.  
  218. 9.  Every RIPscrip command includes a command type character.  In
  219.     Level-0 commands, this character immediately follows the vertical
  220.     bar.  At all other levels, it follows the level digits.  The
  221.     command type character may be any printable non-decimal-digit
  222.     character.
  223.  
  224. 10. Following the command type character are 0 or more parameters.
  225.     If the command requires a text-string, it is always the LAST
  226.     parameter.  Numeric parameters DO NOT have any delimiters
  227.     (commas, dashes, spaces, etc.).  A variable width numeric
  228.     parameter may be used as the last parameter.  This allows for
  229.     maximum efficiency.  Numbers are represented in base-36.  This
  230.     compacts numbers down to roughly 3/5 of their decimal form.
  231.     This numbering system, technically called "Hexa-Tri-Decimal",
  232.     has affectionately been dubbed "MegaNums".  Unlike Hexadecimal
  233.     which uses 0-9, A-F, MegaNums take advantage of the entire
  234.     alphabet, using characters 0-9 and A-Z.
  235.  
  236. 11. An exclamation mark (!) or vertical bar (|) character can appear
  237.     in a RIPscrip text parameter by preceding it with a backslash(\).
  238.     A literal backslash is represented with a double-backslash (\\).
  239.  
  240. 12. A RIPscrip sequence CAN begin in a column other than column #0,
  241.     if the exclamation mark prefix is replaced with a Ctrl-A (Start
  242.     Of Header [SOH]) character, or Ctrl-B (STX) character.  Since
  243.     99.9% of all BBS' do not allow users to enter most control
  244.     characters, users will be unable to begin RIPscrip sequences in
  245.     the middle of a command line.  Only the host should be able to
  246.     do this.  This prevents people from cluttering  teleconference,
  247.     or other areas of a host with spurious RIPscrip sequences.
  248.  
  249. 13. If the last couple of bytes on a RIPscrip text line are           > v1.54
  250.     backslashes, special care must be taken to make sure that they    > v1.54
  251.     are not interpretted as a line-continuation.  If a literal        > v1.54
  252.     backslash is desired as the last position on the line, it must    > v1.54
  253.     be specified as a double-backslash (eg, "\\").  If a line-        > v1.54
  254.     continuation is used then there would have to be three            > v1.54
  255.     backslashes used on the line as in the following example:         > v1.54
  256.                                                                       > v1.54
  257.         !|@2233this is a text line with a literal \\\                 > v1.54
  258.         used in the message                                           > v1.54
  259.                                                                       > v1.54
  260.     This would text output at (22,33) [meganum] the message:          > v1.54
  261.                                                                       > v1.54
  262.        this is a text line with a literal \used in the message        > v1.54
  263.  
  264.  
  265.  
  266.  
  267. =====================================================================
  268. ==                   ANSI SEQUENCES (AUTO-SENSING)                 ==
  269. =====================================================================
  270.  
  271. RIPscrip predominantly uses non-ANSI command sequences.  In a couple
  272. of situations though, an ANSI sequence is allowed to perform a
  273. specific function.  There are currently three separate ANSI sequences
  274. defined in the RIPscrip protocol to perform various actions.  They
  275. are as follows:
  276.  
  277. ESC[!     Query RIPscrip version number.  RIPterm will respond with   > v1.54
  278.           RIPSCRIPxxyyvs where "xx" is equal to the major version     > v1.54
  279.           number (zero padded), "yy" is equal to the minor version    > v1.54
  280.           number (zero padded), "v" is the vendor code of the         > v1.54
  281.           terminal program (see below), and "s" is the vendor's       > v1.54
  282.           sub-version code for their software.  For v1.54, the        > v1.54
  283.           returned sequence for RIPterm (Vendor Code "1") would be    > v1.54
  284.           RIPSCRIP015410.  Another example, v1.23 with a Vendor Code  > v1.54
  285.           of "2" and a sub-revision code of "5" would return          > v1.54
  286.           RIPSCRIP012325.                                             > v1.54
  287.                                                                       > v1.54
  288.           Valid Vendor Codes are:                                     > v1.54
  289.                                                                       > v1.54
  290.                CODE   VENDOR                                          > v1.54
  291.                =================================================      > v1.54
  292.                  0    Generic RIPscrip terminal (vendor unknown)      > v1.54
  293.                  1    RIPterm (from TeleGrafix Communications)        > v1.54
  294.                  2    Qmodem Pro (from Mustang Software, Inc)         > v1.54
  295.                                                                       > v1.54
  296.           This ANSI sequence is often used for "Auto-Sensing" if a    > v1.54
  297.           RIPscrip terminal exists on the remote end of the           > v1.54
  298.           connection.  If a non-RIPscrip terminal receives this       > v1.54
  299.           ANSI sequence, it will ignore it.                           > v1.54
  300.  
  301. ESC[0!    Same as ESC [ ! (see above)
  302.  
  303. ESC[1!    Disables all RIPscrip processing.  Any RIPscrip sequences
  304.           are interpreted as raw text.
  305.  
  306. ESC[2!    Enabled RIPscrip processing.  Any RIPscrip sequences will
  307.           be parsed and processed.
  308.  
  309.  
  310.  
  311.  
  312. =====================================================================
  313. ==                 MISCELLANEOUS NOTES/INFORMATION                 ==
  314. =====================================================================
  315.  
  316. Later in this document, references are made to Mouse Fields and Mouse > v1.54
  317. Buttons.  Specifically, it is noted that up to 128 of these types of  > v1.54
  318. commands may exist simultaneously on-screen.  This means that you can > v1.54
  319. have 128 mouse fields, 128 mouse buttons, or any combination of the   > v1.54
  320. above, but combined, their total number cannot exceed 128.            > v1.54
  321.  
  322. When the user clicks his/her mouse on the screen, all mouse regions   > v1.54
  323. (whether mouse fields or mouse buttons) are scanned from most recent  > v1.54
  324. to the least recent.  This means that if a mouse region is received   > v1.54
  325. that overlaps another mouse region, that one would be clicked first   > v1.54
  326. if the user clicked in that region.                                   > v1.54
  327.  
  328. If you are implementing a client terminal to support RIPscrip         > v1.54
  329. graphics and you do not intend on supporting 100% of all pre-defined  > v1.54
  330. text variables, you SHOULD at least recognize them and do nothing.    > v1.54
  331. This makes it so that if a particular text variable is used to make   > v1.54
  332. a sound (for example), then if you don't support it, you just ignore  > v1.54
  333. it instead of popping up a dialog box on your user's screen asking    > v1.54
  334. them to enter data for the variable $MUSIC$ for example!              > v1.54
  335.  
  336.  
  337.  
  338.  
  339. =====================================================================
  340. ==                    RIPscrip COMMAND REFERENCE                   ==
  341. =====================================================================
  342.  
  343. The remainder of this document details the RIPscrip command set.
  344. Each command has these aspects:
  345.  
  346.     SYMBOL - the symbolic constant that is referenced in the
  347.              RIPscrip API Library code.  This is  the universal
  348.              name for the command.
  349.  
  350.      LEVEL - The Command Level.  Sub-levels are represented
  351.              with decimal points (eg, 1.3.5 for Level-1,
  352.              Sub-level 3, Sub-Sub-level 5).  This is for
  353.              discussion purposes only.  The decimal points
  354.              are never part of the actual command.
  355.  
  356.    COMMAND - The command type character identifying the
  357.              command
  358.  
  359.  ARGUMENTS - The arguments or parameters for the command.
  360.              Commands that do not require any arguments
  361.              after the command type character are shown
  362.              here as "<none>".  Each argument is shown in
  363.              the order it appears in the command, and is
  364.              represented by a name.  If an argument is
  365.              numeric, it is followed by a width specifier
  366.              indicating how many MegaNum digits the
  367.              argument consists of.  (eg, ":2" means a
  368.              2-digit MegaNum, or a value between 0 and
  369.              1295).  If an argument does not have a width
  370.              specifier, it is by default a text argument,
  371.              and should be the last argument on the line.
  372.              If a command is variable length (see POLYGON),
  373.              then it will appear with ellipses (...)
  374.  
  375.     FORMAT - This represents the format of the command, with
  376.              the starting "!|", the level digits, the
  377.              command type character, and the argument list,
  378.              with the argument names in angle brackets.
  379.              (These arguments are spaced apart, but these
  380.              spaces never appear in the physical commands.)
  381.  
  382.    EXAMPLE - An actual example of the RIPscrip command.
  383.  
  384. DRAW COLOR - If YES, then this command uses or affects the
  385.              current Drawing Color.
  386.  
  387. LINE PATRN - If YES, then this command uses or affects the
  388.              current Line Style Pattern.
  389.  
  390. LINE THICK - If YES, then this command uses or affects the
  391.              current Line Style Thickness
  392.  
  393. FILL COLOR - If YES, then this command uses or affects the
  394.              current Fill Color.
  395.  
  396. FILL PATRN - If YES, then this command uses or affects the
  397.              current Fill Pattern.
  398.  
  399. WRITE MODE - If YES, then this command will take advantage
  400.              of the current Write Mode (eg, COPY, or XOR).
  401.  
  402. FONT SIZES - If YES, then this command uses or affects the
  403.              current Font Size.
  404.  
  405. VIEWPORT   - If YES, then this command adheres to the                 > v1.54
  406.              graphical viewport (draws inside it).  Any               > v1.54
  407.              RIPscrip command that adheres to the graphical           > v1.54
  408.              viewport will be drawn (when received) only              > v1.54
  409.              if the viewport is defined.  If the viewport             > v1.54
  410.              is not defined (0,0,0,0), then the command is            > v1.54
  411.              parsed, but completely ignored.                          > v1.54
  412.  
  413.  
  414.  
  415.  
  416.  
  417. ---------------------------------------------------------------------
  418. RIP_TEXT_WINDOW
  419. ---------------------------------------------------------------------
  420.          Function:  Define the size and location of the Text Window
  421.             Level:  0
  422.           Command:  w
  423.         Arguments:  x0:2, y0:2, x1:2, y1:2, wrap:1, size:1
  424.            Format:  !|w <x0> <y0> <x1> <y1> <wrap> <size>
  425.           Example:  !|w00001B0M10
  426.   Uses Draw Color:  NO
  427. Uses Line Pattern:  NO
  428.   Uses Line Thick:  NO
  429.   Uses Fill Color:  NO
  430. Uses Fill Pattern:  NO
  431.   Uses Write Mode:  NO
  432.   Uses Font Sizes:  NO
  433.     Uses Viewport:  NO                                                > v1.54
  434.  
  435. This command specifies the dimensions of the virtual TTY window that
  436. will display all ASCII/ANSI (non-RIPscrip) data coming across the
  437. connection.  (x0,y0) defines the upper-left corner of the window in
  438. text-based character- cell coordinates.  (x1,y1) defines the
  439. lower-right corner of the window (inclusive).  There may be two
  440. simultaneous windows on the screen, one for TTY text, and one for the
  441. display of RIPscrip graphics (a viewport), and they may overlap.
  442.  
  443. Bytes received over the modem are first checked for RIPscrip
  444. commands.  All bytes that don't conform to the RIPscrip syntax are
  445. treated as ANSI/ASCII and displayed in the TTY window (if defined).
  446. User keystrokes that are echoed by the BBS would also appear in the
  447. text window by this scheme.
  448.  
  449. The text window may be made invisible, ignoring all non-RIPscrip
  450. bytes, by setting all RIP_TEXT_WINDOW parameters to zero (0).  The X
  451. and Y parameters ranges vary depending on the setting of the <size>
  452. parameter which governs the font size used for the output text. Valid
  453. settings for the <size> parameter and the ranges for X/Y values are
  454. as follows:
  455.  
  456.         Size   Font Size   X Range  Y Range
  457.         ------------------------------------------
  458.          0     8x8          0-79     0-42
  459.          1     7x8          0-90     0-42
  460.          2     8x14         0-79     0-24
  461.          3     7x14         0-90     0-24
  462.          4     16x14        0-39     0-24
  463.  
  464. The <wrap> parameter applies to both the horizontal and vertical
  465. dimensions.  If <wrap> is set to 1, then any text that extends beyond
  466. the right margin of the window will wrap to the next line of the
  467. window, scrolling the window up if necessary.  If <wrap> is 0, then
  468. any text going beyond the right margin is truncated and no scrolling
  469. is performed; the cursor remains at the right margin.
  470.  
  471. NOTE:  If the text window currently being defined is identical to the
  472.        currently defined text window, the cursor will not be
  473.        relocated to the upper-left corner of the window. The only
  474.        aspect of the text window that can be different and still be
  475.        deemed "identical" is the <wrap> parameter.  For the current
  476.        and new text windows to be considered identical, the
  477.        parameters <x0>, <y0>, <x1>, <y1> and <size> must be the same.
  478.  
  479.  
  480.  
  481. ---------------------------------------------------------------------
  482. RIP_VIEWPORT
  483. ---------------------------------------------------------------------
  484.          Function:  Define the size & location of the Graphics Window
  485.             Level:  0
  486.           Command:  v
  487.         Arguments:  x0:2, y0:2, x1:2, y1:2
  488.            Format:  !|v <x0> <y0> <x1> <y1>
  489.           Example:  !|v00002E1M
  490.   Uses Draw Color:  NO
  491. Uses Line Pattern:  NO
  492.   Uses Line Thick:  NO
  493.   Uses Fill Color:  NO
  494. Uses Fill Pattern:  NO
  495.   Uses Write Mode:  NO
  496.   Uses Font Sizes:  NO
  497.     Uses Viewport:  NO                                                > v1.54
  498.  
  499. This command defines the (X,Y) pixel boundaries of the RIPscrip
  500. graphics window, which will contain all RIPscrip graphics output.
  501. ASCII/ANSI text will be displayed in the virtual TTY window defined
  502. by the RIP_TEXT_WINDOW command above.  (x0,y0) defines the upper-left
  503. corner of the graphics viewport, and (x1,y1) defines the lower-right
  504. corner (inclusive).  The viewport may be disabled, so RIPscrip
  505. graphics commands are ignored, by setting all parameters to zero (0).
  506.  
  507. Graphics displayed in the viewport are "truncated" at this rectangular
  508. border, meaning if a circle would normally extend outside one of the
  509. borders, it will be chopped, only displaying the portion of the
  510. circle that is contained inside the viewport boundaries.
  511.  
  512. Coordinates are specified based on a 640x350 pixel resolution, meaning
  513. X can be anywhere from 0 - 639, and Y can be anywhere from 0 - 349.
  514. x0 must be less than x1 and y0 must be less than y1 unless all
  515. parameters are set to zero, indicating that the graphics window is
  516. disabled.
  517.  
  518.  
  519.  
  520. ---------------------------------------------------------------------
  521. RIP_RESET_WINDOWS
  522. ---------------------------------------------------------------------
  523.          Function:  Clear Graphics/Text Windows & reset to full screen
  524.             Level:  0
  525.           Command:  *
  526.         Arguments:  <none>
  527.            Format:  !|*
  528.           Example:  !|*
  529.   Uses Draw Color:  NO
  530. Uses Line Pattern:  NO
  531.   Uses Line Thick:  NO
  532.   Uses Fill Color:  NO
  533. Uses Fill Pattern:  NO
  534.   Uses Write Mode:  NO
  535.   Uses Font Sizes:  NO
  536.     Uses Viewport:  NO                                                > v1.54
  537.  
  538. This command will set the Text Window to a full 80x43 EGA hi-res text
  539. mode, place the cursor in the upper left corner, clear the screen,
  540. and zoom the Graphics Window to full 640x350 EGA screen.  Both
  541. windows are filled with the current graphics background color.  Also, > v1.54
  542. all Mouse Regions and Mouse Buttons are deleted and the Clipboard is  > v1.54
  543. erased.  A system One might use this function before entering a text  > v1.54
  544. only mode that does not support RIP commands.  This command will also
  545. restore the default 16-color RIP palette (see RIP_SET_PALETTE below).
  546.  
  547.  
  548.  
  549. ---------------------------------------------------------------------
  550. RIP_ERASE_WINDOW
  551. ---------------------------------------------------------------------
  552.          Function:  Clears Text Window to current background color
  553.             Level:  0
  554.           Command:  e
  555.         Arguments:  <none>
  556.            Format:  !|e
  557.           Example:  !|e
  558.   Uses Draw Color:  NO
  559. Uses Line Pattern:  NO
  560.   Uses Line Thick:  NO
  561.   Uses Fill Color:  NO
  562. Uses Fill Pattern:  NO
  563.   Uses Write Mode:  NO
  564.   Uses Font Sizes:  NO
  565.     Uses Viewport:  NO                                                > v1.54
  566.  
  567. This clears the TTY text window to the current graphics background
  568. color and positions the cursor in the upper-left corner of the
  569. window.  If the text window is inactive, then this command is
  570. ignored.  If the text and graphics windows overlap, then this command
  571. will clear the overlapping portion also.
  572.  
  573.  
  574.  
  575. ---------------------------------------------------------------------
  576. RIP_ERASE_VIEW
  577. ---------------------------------------------------------------------
  578.          Function:  Clear Graphics Window to current background color
  579.             Level:  0
  580.           Command:  E
  581.         Arguments:  <none>
  582.            Format:  !|E
  583.           Example:  !|E
  584.   Uses Draw Color:  NO
  585. Uses Line Pattern:  NO
  586.   Uses Line Thick:  NO
  587.   Uses Fill Color:  NO
  588. Uses Fill Pattern:  NO
  589.   Uses Write Mode:  NO
  590.   Uses Font Sizes:  NO
  591.     Uses Viewport:  NO                                                > v1.54
  592.  
  593. This command clears the Graphics Viewport to the current graphics
  594. background color.  If the graphics viewport is not active (if the
  595. boundaries are 0,0,0,0), then this command is ignored.  If the text
  596. and graphics windows overlap, then this command will clear the
  597. overlapping portion also.
  598.  
  599.  
  600.  
  601. ---------------------------------------------------------------------
  602. RIP_GOTOXY
  603. ---------------------------------------------------------------------
  604.          Function:  Move text cursor to row & column in Text Window
  605.             Level:  0
  606.           Command:  g
  607.         Arguments:  x:2, y:2
  608.            Format:  !|g <x> <y>
  609.           Example:  !|g0509
  610.   Uses Draw Color:  NO
  611. Uses Line Pattern:  NO
  612.   Uses Line Thick:  NO
  613.   Uses Fill Color:  NO
  614. Uses Fill Pattern:  NO
  615.   Uses Write Mode:  NO
  616.   Uses Font Sizes:  NO
  617.     Uses Viewport:  NO                                                > v1.54
  618.  
  619. This command sets the position of the text cursor in the TTY Text
  620. window, if it is active.  If inactive (if the dimensions are
  621. 0,0,0,0), then this command is ignored.  This command is equivalent
  622. to the ANSI/VT-100 command goto x/y, <Esc>[x;yH, except that the
  623. coordinates of that ANSI command are 1-based and the coordinates of
  624. this RIPscrip command are 0-based.
  625.  
  626.  
  627.  
  628. ---------------------------------------------------------------------
  629. RIP_HOME
  630. ---------------------------------------------------------------------
  631.          Function:  Move cursor to upper-left corner of Text Window
  632.             Level:  0
  633.           Command:  H
  634.         Arguments:  <none>
  635.            Format:  !|H
  636.           Example:  !|H
  637.   Uses Draw Color:  NO
  638. Uses Line Pattern:  NO
  639.   Uses Line Thick:  NO
  640.   Uses Fill Color:  NO
  641. Uses Fill Pattern:  NO
  642.   Uses Write Mode:  NO
  643.   Uses Font Sizes:  NO
  644.     Uses Viewport:  NO                                                > v1.54
  645.  
  646. This command positions the text cursor to the upper-left corner in
  647. the TTY Text Window, if it is active.
  648.  
  649.  
  650.  
  651. ---------------------------------------------------------------------
  652. RIP_ERASE_EOL
  653. ---------------------------------------------------------------------
  654.          Function:  Erase current line from cursor to end of line
  655.             Level:  0
  656.           Command:  >
  657.         Arguments:  <none>
  658.            Format:  !|>
  659.           Example:  !|>
  660.   Uses Draw Color:  NO
  661. Uses Line Pattern:  NO
  662.   Uses Line Thick:  NO
  663.   Uses Fill Color:  NO
  664. Uses Fill Pattern:  NO
  665.   Uses Write Mode:  NO
  666.   Uses Font Sizes:  NO
  667.     Uses Viewport:  NO                                                > v1.54
  668.  
  669. This command will erase the current text line in the TTY text window
  670. from the current cursor location (inclusive) to the end of the line.
  671. The erased region is filled with the current graphics background
  672. color.  This differs from the ANSI command ESC[K which clears the
  673. area with the current ANSI background color.
  674.  
  675.  
  676.  
  677. ---------------------------------------------------------------------
  678. RIP_COLOR
  679. ---------------------------------------------------------------------
  680.          Function:  Set current Drawing Color for graphics
  681.             Level:  0
  682.           Command:  c
  683.         Arguments:  color:2
  684.            Format:  !|c <color>
  685.           Example:  !|cA
  686.   Uses Draw Color:  YES
  687. Uses Line Pattern:  NO
  688.   Uses Line Thick:  NO
  689.   Uses Fill Color:  NO
  690. Uses Fill Pattern:  NO
  691.   Uses Write Mode:  NO
  692.   Uses Font Sizes:  NO
  693.     Uses Viewport:  NO                                                > v1.54
  694.  
  695. This command sets the color for drawing lines, circles, arcs,
  696. rectangles, and other graphics primitives, as well as the color for
  697. drawing graphics-text from the RIP_TEXT class of commands (not from
  698. ASCII/ANSI text).  This command does not affect Fill colors or Fill
  699. Patterns (see below).  It does affect the borders of graphic objects,
  700. for example the border of an ellipse drawn with the RIP_FILLED_OVAL
  701. command.  (The interior of the ellipse would be drawn according to
  702. the most recent RIP_FILL_STYLE command.)
  703.  
  704. This command chooses one of the colors of the 16-color RIP palette
  705. defined by the RIP_SET_PALETTE.  Here is the default 16-color RIP
  706. palette:
  707.  
  708.      Value   Color
  709.      -------------------------------------------------------
  710.      00      Black (00 is always the background color)
  711.      01      Blue
  712.      02      Green
  713.      03      Cyan
  714.      04      Red
  715.      05      Magenta
  716.      06      Brown
  717.      07      Light Gray
  718.      08      Dark Gray
  719.      09      Light Blue
  720.      0A      Light Green
  721.      0B      Light Cyan
  722.      0C      Light Red
  723.      0D      Light Magenta
  724.      0E      Yellow
  725.      0F      White
  726.  
  727.  
  728.  
  729. ---------------------------------------------------------------------
  730. RIP_SET_PALETTE
  731. ---------------------------------------------------------------------
  732.          Function:  Set 16-color Palette from master 64-color palette
  733.             Level:  0
  734.           Command:  Q
  735.         Arguments:  c1:2, c2:2, ... c16:2
  736.            Format:  !|Q <c1> <c2> ... <c16>
  737.           Example:  !|Q000102030405060708090A0B0C0D0E0F
  738.   Uses Draw Color:  YES
  739. Uses Line Pattern:  NO
  740.   Uses Line Thick:  NO
  741.   Uses Fill Color:  NO
  742. Uses Fill Pattern:  NO
  743.   Uses Write Mode:  NO
  744.   Uses Font Sizes:  NO
  745.     Uses Viewport:  NO                                                > v1.54
  746.  
  747. This command modifies the 16-color RIP palette by choosing from the
  748. 64 colors in the master palette.  This allows you to alter the colors
  749. in your RIPscrip graphics scenes.  Once a Set Palette command is
  750. processed, any colors on the screen that had their corresponding
  751. palette entries changed will instantly switch to the new color set.
  752. You may obtain color cycling effects by using this command.  The
  753. default 16-color RIP palette is restored by the RIP_RESET_WINDOWS
  754. command.  The default 16-color RIP palette is:
  755.  
  756.     16-Color RIP Palette     Master 64-Color EGA
  757.         Color Code           Palette Color Code       Color
  758.     ---------------------------------------------------------------
  759.            00                     0  (00)             Black
  760.            01                     1  (01)             Blue
  761.            02                     2  (02)             Green
  762.            03                     3  (03)             Cyan
  763.            04                     4  (04)             Red
  764.            05                     5  (05)             Magenta
  765.            06                     7  (06)             Brown
  766.            07                     20 (0K)             Light Gray
  767.            08                     56 (1K)             Dark Gray
  768.            09                     57 (1L)             Light Blue
  769.            0A                     58 (1M)             Light Green
  770.            0B                     59 (1N)             Light Cyan
  771.            0C                     60 (1O)             Light Red
  772.            0D                     61 (1P)             Light Magenta
  773.            0E                     62 (1Q)             Yellow
  774.            0F                     63 (1R)             White
  775.  
  776. Color 00 of the 16-color RIP palette is always the background color
  777. (which is typically Black, or color 00 of the 64-color EGA palette).
  778.  
  779.  
  780.  
  781. ---------------------------------------------------------------------
  782. RIP_ONE_PALETTE
  783. ---------------------------------------------------------------------
  784.          Function:  Set color of 16-color Palette from Master Palette
  785.             Level:  0
  786.           Command:  a
  787.         Arguments:  color:2 value:2
  788.            Format:  !|a <color> <value>
  789.           Example:  !|a051B
  790.   Uses Draw Color:  YES
  791. Uses Line Pattern:  NO
  792.   Uses Line Thick:  NO
  793.   Uses Fill Color:  NO
  794. Uses Fill Pattern:  NO
  795.   Uses Write Mode:  NO
  796.   Uses Font Sizes:  NO
  797.     Uses Viewport:  NO                                                > v1.54
  798.  
  799. This command changes one color in the 16-color palette.  The color
  800. number is sent along with the new color value from the Master Color
  801. Palette. The color <value> must be in the range of 0-63.  Once a Set
  802. One Palette command is processed, any colors on the screen that
  803. correspond to the <color> number will be changed instantly to the new
  804. color value.  You may obtain color cycling effects by using this
  805. command.  The default RIP palette is restored when by
  806. RIP_RESET_WINDOWS.
  807.  
  808.     16-Color RIP Palette     Master 64-Color EGA
  809.         Color Code           Palette Color Code       Color
  810.     ---------------------------------------------------------------
  811.            00                     0  (00)             Black
  812.            01                     1  (01)             Blue
  813.            02                     2  (02)             Green
  814.            03                     3  (03)             Cyan
  815.            04                     4  (04)             Red
  816.            05                     5  (05)             Magenta
  817.            06                     7  (06)             Brown
  818.            07                     20 (0K)             Light Gray
  819.            08                     56 (1K)             Dark Gray
  820.            09                     57 (1L)             Light Blue
  821.            0A                     58 (1M)             Light Green
  822.            0B                     59 (1N)             Light Cyan
  823.            0C                     60 (1O)             Light Red
  824.            0D                     61 (1P)             Light Magenta
  825.            0E                     62 (1Q)             Yellow
  826.            0F                     63 (1R)             White
  827.  
  828. Color 00 of the 16-color RIP palette is always the background color
  829. (which is typically Black, or color 00 of the 64-color EGA palette).
  830.  
  831.  
  832.  
  833. ---------------------------------------------------------------------
  834. RIP_WRITE_MODE
  835. ---------------------------------------------------------------------
  836.          Function:  Set drawing mode for graphics primitives
  837.             Level:  0
  838.           Command:  W
  839.         Arguments:  mode:2
  840.            Format:  !|W <mode>
  841.           Example:  !|W00
  842.   Uses Draw Color:  NO
  843. Uses Line Pattern:  NO
  844.   Uses Line Thick:  NO
  845.   Uses Fill Color:  NO
  846. Uses Fill Pattern:  NO
  847.   Uses Write Mode:  YES
  848.   Uses Font Sizes:  NO
  849.     Uses Viewport:  NO                                                > v1.54
  850.  
  851. This command sets the current drawing mode for most of the graphics
  852. primitives:
  853.  
  854.      Mode   Description
  855.      ------------------------------------------
  856.      00     Normal drawing mode (overwrite)
  857.      01     XOR (complimentary) mode
  858.  
  859. In normal mode, things are drawn in the current drawing color over top
  860. of whatever is in the graphics viewport.  This is the typical mode of
  861. operation in a GUI environment.
  862.  
  863. In the XOR mode, instead of changing each pixel to the current
  864. drawing color, the pixel is inverted (black changes to white, red to
  865. green, etc.).  Drawing the same item a second time erases it
  866. completely.  This mode is useful for drawing something temporarily,
  867. or for animation.  The Rubber Band mode of most paint programs uses a
  868. mode like this.
  869.  
  870.  
  871.  
  872. ---------------------------------------------------------------------
  873. RIP_MOVE
  874. ---------------------------------------------------------------------
  875.          Function:  Move the current drawing position to (X,Y)
  876.             Level:  0
  877.           Command:  m
  878.         Arguments:  x:2, y:2
  879.            Format:  !|m <x> <y>
  880.           Example:  !|m0509
  881.   Uses Draw Color:  NO
  882. Uses Line Pattern:  NO
  883.   Uses Line Thick:  NO
  884.   Uses Fill Color:  NO
  885. Uses Fill Pattern:  NO
  886.   Uses Write Mode:  NO
  887.   Uses Font Sizes:  NO
  888.     Uses Viewport:  YES                                               > v1.54
  889.  
  890. This command moves the current graphics drawing cursor to (x,y).  You
  891. could use this to draw text at a certain point, but you'd probably
  892. use RIP_TEXT_XY instead.  This command is primarily provided for
  893. future development which will make use of its ability to relocate the
  894. current drawing position without physically drawing anything.
  895.  
  896.  
  897.  
  898. ---------------------------------------------------------------------
  899. RIP_TEXT
  900. ---------------------------------------------------------------------
  901.          Function:  Draw text in current font/color at current spot
  902.             Level:  0
  903.           Command:  T
  904.         Arguments:  text-string
  905.            Format:  !|T <text-string>
  906.           Example:  !|Thello world
  907.   Uses Draw Color:  YES
  908. Uses Line Pattern:  NO
  909.   Uses Line Thick:  NO
  910.   Uses Fill Color:  NO
  911. Uses Fill Pattern:  NO
  912.   Uses Write Mode:  YES
  913.   Uses Font Sizes:  YES
  914.     Uses Viewport:  YES                                               > v1.54
  915.  
  916. This command displays text at the current location in the graphics
  917. window, as set with the RIP_MOVE command.  The text is also affected
  918. by the most recent settings of these commands:
  919.  
  920.      Command            Description of Command
  921.      ----------------------------------------------------------------
  922.      RIP_FONT_STYLE     font style (character set, direction, size)
  923.      RIP_WRITE_MODE     drawing mode (normal or XOR)
  924.      RIP_COLOR          drawing color (from the 16-color RIP palette)
  925.  
  926. The drawing position is placed at the end of the last character
  927. drawn.
  928.  
  929. The current drawing position is set immediately to the right of the
  930. drawn text.  Subsequent Line, Circle or other such commands will not
  931. affect this position.  This provides a means so that you can quickly
  932. do another RIP_TEXT command (presumably in another color) at a later
  933. time and have the text show up immediately after the previous text.
  934.  
  935.  
  936.  
  937. ---------------------------------------------------------------------
  938. RIP_TEXT_XY
  939. ---------------------------------------------------------------------
  940.          Function:  Draw text in current font/color at specific spot
  941.             Level:  0
  942.           Command:  @
  943.         Arguments:  x:2, y:2 and text-string
  944.            Format:  !|@ <x> <y> <text-string>
  945.           Example:  !|@0011hello world
  946.   Uses Draw Color:  YES
  947. Uses Line Pattern:  NO
  948.   Uses Line Thick:  NO
  949.   Uses Fill Color:  NO
  950. Uses Fill Pattern:  NO
  951.   Uses Write Mode:  YES
  952.   Uses Font Sizes:  YES
  953.     Uses Viewport:  YES                                               > v1.54
  954.  
  955. This command is an efficient combination of RIP_MOVE and RIP_TEXT.
  956. The text is drawn at the specified location according to the same
  957. settings as apply to RIP_TEXT (see above).
  958.  
  959. The current drawing position is set immediately to the right of the
  960. drawn text.  Subsequent Line, Circle or other such commands will not
  961. affect this position.  This provides a means so that you can quickly
  962. do another RIP_TEXT command (presumably in another color) at a later
  963. time and have the text show up immediately after the previous text.
  964.  
  965.  
  966.  
  967. ---------------------------------------------------------------------
  968. RIP_FONT_STYLE
  969. ---------------------------------------------------------------------
  970.          Function:  Select current font style, orientation and size
  971.             Level:  0
  972.           Command:  Y
  973.         Arguments:  font:2, direction:2, size:2, res:2
  974.            Format:  !|Y <font> <direction> <size> <res>
  975.           Example:  !|Y01000400
  976.   Uses Draw Color:  NO
  977. Uses Line Pattern:  NO
  978.   Uses Line Thick:  NO
  979.   Uses Fill Color:  NO
  980. Uses Fill Pattern:  NO
  981.   Uses Write Mode:  NO
  982.   Uses Font Sizes:  YES
  983.     Uses Viewport:  NO                                                > v1.54
  984.  
  985. This command sets the font, direction and size for RIP_TEXT commands.
  986.  
  987.      Font   Description of Font
  988.      ---------------------------------------------
  989.      00     Default 8x8 font            Bit-Mapped
  990.      01     Triplex Font                Scalable
  991.      02     Small Font                  Scalable
  992.      03     Sans Serif Font             Scalable
  993.      04     Gothic [Old English] Font   Scalable
  994.      05     Script Font                 Scalable
  995.      06     Simplex Font                Scalable
  996.      07     Triplex Script Font         Scalable
  997.      08     Complex Font                Scalable
  998.      09     European Font               Scalable
  999.      0A     Bold Font                   Scalable
  1000.  
  1001. For the Direction parameter, use 00 to indicate horizontal and 01 for
  1002. vertical.
  1003.  
  1004. For the Size parameter, use 01 for the normal default size, 02 for x2
  1005. magnification, 03 for x3 magnification, ... , and 0A for x10
  1006. magnification.
  1007.  
  1008. NOTE:  The Default font is bit-mapped and looks best when drawn in
  1009.        size 1.  In sizes greater than one, the individual pixels are
  1010.        enlarged, giving a jagged look.  This may not be the desired
  1011.        effect.  The fonts 1 - 4 are smooth scalable vector fonts.
  1012.  
  1013.  
  1014.  
  1015. ---------------------------------------------------------------------
  1016. RIP_PIXEL
  1017. ---------------------------------------------------------------------
  1018.          Function:  Draws a one pixel using current drawing color
  1019.             Level:  0
  1020.           Command:  X
  1021.         Arguments:  x:2, y:2
  1022.            Format:  !|X <x> <y>
  1023.           Example:  !|X1122
  1024.   Uses Draw Color:  YES
  1025. Uses Line Pattern:  NO
  1026.   Uses Line Thick:  NO
  1027.   Uses Fill Color:  NO
  1028. Uses Fill Pattern:  NO
  1029.   Uses Write Mode:  NO
  1030.   Uses Font Sizes:  NO
  1031.     Uses Viewport:  YES                                               > v1.54
  1032.  
  1033. This command will draw a single pixel in the current drawing color at
  1034. the given (x,y) graphics position.  This command is included for
  1035. completeness, but in practice it would be extremely inefficient to
  1036. make much use of it.
  1037.  
  1038.  
  1039.  
  1040. ---------------------------------------------------------------------
  1041. RIP_LINE
  1042. ---------------------------------------------------------------------
  1043.          Function:  Draw a line in the current color/line style
  1044.             Level:  0
  1045.           Command:  L
  1046.         Arguments:  x0:2, y0:2, x1:2, y1:2
  1047.            Format:  !|L <x0> <y0> <x1> <y1>
  1048.           Example:  !|L00010A0E
  1049.   Uses Draw Color:  YES
  1050. Uses Line Pattern:  YES
  1051.   Uses Line Thick:  YES
  1052.   Uses Fill Color:  NO
  1053. Uses Fill Pattern:  NO
  1054.   Uses Write Mode:  YES
  1055.   Uses Font Sizes:  NO
  1056.     Uses Viewport:  YES                                               > v1.54
  1057.  
  1058. This command will draw a line in the current drawing color, using the
  1059. current line style, pattern and thickness.  The line is drawn from
  1060. (x0,y0) to (x1,y1) in the graphics viewport.
  1061.  
  1062.  
  1063.  
  1064. ---------------------------------------------------------------------
  1065. RIP_RECTANGLE
  1066. ---------------------------------------------------------------------
  1067.          Function:  Draw a rectangle in current color/line style
  1068.             Level:  0
  1069.           Command:  R
  1070.         Arguments:  x0:2, y0:2, x1:2, y1:2
  1071.            Format:  !|R <x0> <y0> <x1> <y1>
  1072.           Example:  !|R00010A0E
  1073.   Uses Draw Color:  YES
  1074. Uses Line Pattern:  YES
  1075.   Uses Line Thick:  YES
  1076.   Uses Fill Color:  NO
  1077. Uses Fill Pattern:  NO
  1078.   Uses Write Mode:  YES
  1079.   Uses Font Sizes:  NO
  1080.     Uses Viewport:  YES                                               > v1.54
  1081.  
  1082. This command draws a rectangle in the current drawing color, using
  1083. the current line style, pattern and thickness.  (x0,y0) and (x1,y1)
  1084. are any two opposing corners of the rectangle.  If x0=x1 or y0=y1
  1085. then the command will draw a single vertical or horizontal line.  The
  1086. rectangle interior is not filled by RIP_RECTANGLE.
  1087.  
  1088.  
  1089.  
  1090. ---------------------------------------------------------------------
  1091. RIP_BAR
  1092. ---------------------------------------------------------------------
  1093.          Function:  Draw filled rectangle with fill color/pattern
  1094.             Level:  0
  1095.           Command:  B
  1096.         Arguments:  x0:2, y0:2, x1:2, y1:2
  1097.            Format:  !|B <x0> <y0> <x1> <y1>
  1098.           Example:  !|B00010A0E
  1099.   Uses Draw Color:  NO
  1100. Uses Line Pattern:  NO
  1101.   Uses Line Thick:  NO
  1102.   Uses Fill Color:  YES
  1103. Uses Fill Pattern:  YES
  1104.   Uses Write Mode:  NO
  1105.   Uses Font Sizes:  NO
  1106.     Uses Viewport:  YES                                               > v1.54
  1107.  
  1108. This command fills a rectangular region with the current fill color
  1109. and pattern.  No border is drawn.
  1110.  
  1111.  
  1112.  
  1113. ---------------------------------------------------------------------
  1114. RIP_CIRCLE
  1115. ---------------------------------------------------------------------
  1116.          Function:  Draw circle in current color and line thickness
  1117.             Level:  0
  1118.           Command:  C
  1119.         Arguments:  x_center:2, y_center:2, radius:2
  1120.            Format:  !|C <x_center> <y_center> <radius>
  1121.           Example:  !|C1E180M
  1122.   Uses Draw Color:  YES
  1123. Uses Line Pattern:  NO
  1124.   Uses Line Thick:  YES
  1125.   Uses Fill Color:  NO
  1126. Uses Fill Pattern:  NO
  1127.   Uses Write Mode:  NO
  1128.   Uses Font Sizes:  NO
  1129.     Uses Viewport:  YES                                               > v1.54
  1130.  
  1131. This command draws a circle in the current drawing color and line
  1132. thickness.  The <radius> is in pixel units.  This command understands
  1133. aspect ratios and will draw a truly circular circle instead of an
  1134. oblong circle (ellipse) like on other graphics systems.  The aspect
  1135. ratio is currently based on the EGA 640x350 resolution and is
  1136. understood by both the GUI designer and the Terminal Program.
  1137.  
  1138. NOTE:  This command uses the line thickness setting, but not the line
  1139.        patterns.  In other words, you can draw a circle with a thick
  1140.        or a thin border, but not a dashed or dotted border.
  1141.  
  1142.  
  1143.  
  1144. ---------------------------------------------------------------------
  1145. RIP_OVAL
  1146. ---------------------------------------------------------------------
  1147.          Function:  Draw elliptical arc in current color/line style
  1148.             Level:  0
  1149.           Command:  O
  1150.         Arguments:  x:2, y:2, st_ang:2, end_ang:2, x_rad:2, y_rad:2
  1151.            Format:  !|O <x> <y> <st_ang> <end_ang> <x_rad> <y_rad>
  1152.           Example:  1E1A18003G150Z
  1153.   Uses Draw Color:  YES
  1154. Uses Line Pattern:  NO
  1155.   Uses Line Thick:  YES
  1156.   Uses Fill Color:  NO
  1157. Uses Fill Pattern:  NO
  1158.   Uses Write Mode:  NO
  1159.   Uses Font Sizes:  NO
  1160.     Uses Viewport:  YES                                               > v1.54
  1161.  
  1162. This command draws an elliptical arc similar to the circular RIP_ARC
  1163. command.  The center of the ellipse is (x,y) and the arc is drawn
  1164. starting from <st_ang> and proceeding counterclockwise to <end_ang>
  1165. (see RIP_ARC above for details).
  1166.  
  1167. The X radius is half the full width of the ellipse, the Y radius is
  1168. half the full height.  The ellipse is drawn according to the current
  1169. line thickness, but the current line pattern has no effect.
  1170.  
  1171.  
  1172.  
  1173. ---------------------------------------------------------------------
  1174. RIP_FILLED_OVAL
  1175. ---------------------------------------------------------------------
  1176.          Function:  Draw filled ellipse using current color/pattern
  1177.             Level:  0
  1178.           Command:  o
  1179.         Arguments:  x_center:2, y_center:2, x_rad:2, y_rad:2
  1180.            Format:  !|o <x_center> <y_center> <x_rad> <y_rad>
  1181.           Example:  !|o1G2B0M0G
  1182.   Uses Draw Color:  YES
  1183. Uses Line Pattern:  NO
  1184.   Uses Line Thick:  YES
  1185.   Uses Fill Color:  YES
  1186. Uses Fill Pattern:  YES
  1187.   Uses Write Mode:  NO
  1188.   Uses Font Sizes:  NO
  1189.     Uses Viewport:  YES                                               > v1.54
  1190.  
  1191. This command draws a complete filled ellipse on the screen.  The
  1192. interior of the ellipse is drawn using the current fill pattern and
  1193. fill color.  The outline of the ellipse is drawn using the current
  1194. drawing color and line thickness.
  1195.  
  1196.  
  1197.  
  1198. ---------------------------------------------------------------------
  1199. RIP_ARC
  1200. ---------------------------------------------------------------------
  1201.          Function:  Draw circular arc in current color/line thickness
  1202.             Level:  0
  1203.           Command:  A
  1204.         Arguments:  x:2, y:2, start_ang:2, end_ang:2, radius:2
  1205.            Format:  !|A <x> <y> <start_ang> <end_ang> <radius>
  1206.           Example:  !|A1E18003G15
  1207.   Uses Draw Color:  YES
  1208. Uses Line Pattern:  NO
  1209.   Uses Line Thick:  YES
  1210.   Uses Fill Color:  NO
  1211. Uses Fill Pattern:  NO
  1212.   Uses Write Mode:  NO
  1213.   Uses Font Sizes:  NO
  1214.     Uses Viewport:  YES                                               > v1.54
  1215.  
  1216. This command draws a circular arc, or a segment of a circle.  Drawing
  1217. begins at <start_ang> and terminates at <end_ang>.  The angles are
  1218. represented starting at zero for the 3 o'clock position and
  1219. increasing counterclockwise through a full circle to 360:
  1220.  
  1221.                           90
  1222.                            |
  1223.                      180---|--- 0
  1224.                            |
  1225.                           270
  1226.  
  1227. The arc drawing begins at the <start_angle> and continues counter-
  1228. clockwise to the <end_angle>.  A full circle will be displayed if
  1229. <start_ang>=0 and <end_ang>=360.  This command recognizes aspect
  1230. ratios like the circle command does.  It does not take advantage of
  1231. line patterns but does comply with line thickness.
  1232.  
  1233. If both angles are equal, nothing is drawn.
  1234.  
  1235.  
  1236.  
  1237. ---------------------------------------------------------------------
  1238. RIP_OVAL_ARC
  1239. ---------------------------------------------------------------------
  1240.          Function:  Draw an elliptical arc
  1241.             Level:  0
  1242.           Command:  V
  1243.         Arguments:  x:2, y:2, st_ang:2, e_ang:2, radx:2 rady:2
  1244.            Format:  !|V <x> <y> <st_ang> <e_ang> <radx> <rady>
  1245.           Example:  !|V1E18003G151Q
  1246.   Uses Draw Color:  YES
  1247. Uses Line Pattern:  NO
  1248.   Uses Line Thick:  YES
  1249.   Uses Fill Color:  NO
  1250. Uses Fill Pattern:  NO
  1251.   Uses Write Mode:  NO
  1252.   Uses Font Sizes:  NO
  1253.     Uses Viewport:  YES                                               > v1.54
  1254.  
  1255. This command draws an elliptical arc, or a segment of an ellipse.
  1256. Drawing begins at <st_ang> and terminates at <e_ang>.  The angles are
  1257. represented starting at zero for 3 o'clock position and increasing
  1258. counterclockwise through a full ellipse at 360 degrees:
  1259.  
  1260.                           90
  1261.                            |
  1262.                      180---|--- 0
  1263.                            |
  1264.                           270
  1265.  
  1266. The arc drawing begins at the <st_ang> and continues counterclockwise
  1267. to the <e_ang>.  A complete ellipse will be displayed if <st_ang>=0
  1268. and <e_ang>=360.  This command does not utilize "aspect ratios"
  1269. because of the nature of an Ellipse.  It does not take advantage of
  1270. line patterns but does comply with line thickness.
  1271.  
  1272.  
  1273.  
  1274. ---------------------------------------------------------------------
  1275. RIP_PIE_SLICE
  1276. ---------------------------------------------------------------------
  1277.          Function:  Draws a circular pie slice
  1278.             Level:  0
  1279.           Command:  I
  1280.         Arguments:  x:2, y:2, start_ang:2, end_ang:2, radius:2
  1281.            Format:  !|I <x> <y> <start_ang> <end_ang> <radius>
  1282.           Example:  !|I1E18003G15
  1283.   Uses Draw Color:  YES
  1284. Uses Line Pattern:  NO
  1285.   Uses Line Thick:  YES
  1286.   Uses Fill Color:  YES
  1287. Uses Fill Pattern:  YES
  1288.   Uses Write Mode:  NO
  1289.   Uses Font Sizes:  NO
  1290.     Uses Viewport:  YES                                               > v1.54
  1291.  
  1292. This command draws a "pie slice".  The slice is circular.  It obeys
  1293. all of the same commands as the Arc command described above.  The
  1294. ends of the arc are connected to the Center-Point of the Arc with two
  1295. straight lines.  These two lines converge at the Center-Point.  The
  1296. interior of the Slice is filled with the current Fill Color and
  1297. Pattern.  The exterior (outline) of the Slice is drawn using the
  1298. current drawing color and line thickness.  The Line Pattern feature
  1299. does not apply to this command.
  1300.  
  1301.  
  1302.  
  1303. ---------------------------------------------------------------------
  1304. RIP_OVAL_PIE_SLICE
  1305. ---------------------------------------------------------------------
  1306.          Function:  Draws an elliptical pie slice
  1307.             Level:  0
  1308.           Command:  i
  1309.         Arguments:  x:2, y:2, st_ang:2, e_ang:2, radx:2 rady:2
  1310.            Format:  !|i <x> <y> <st_ang> <e_ang> <radx> <rady>
  1311.           Example:  !|i1E18003G151Q
  1312.   Uses Draw Color:  YES
  1313. Uses Line Pattern:  NO
  1314.   Uses Line Thick:  YES
  1315.   Uses Fill Color:  YES
  1316. Uses Fill Pattern:  YES
  1317.   Uses Write Mode:  NO
  1318.   Uses Font Sizes:  NO
  1319.     Uses Viewport:  YES                                               > v1.54
  1320.  
  1321. This command draws an  "elliptical pie slice".  It obeys all of the
  1322. same commands as the Elliptical Arc command described above.  The
  1323. ends of the arc are connected to the Center-Point of the Arc with two
  1324. straight lines.  These two lines converge at the Center-Point.  The
  1325. interior of the Slice is filled with the current Fill Color and
  1326. Pattern.  The exterior (outline) of the Slice is drawn using the
  1327. current drawing color and line thickness.  The Line Pattern feature
  1328. does not apply to this command.
  1329.  
  1330.  
  1331.  
  1332. ---------------------------------------------------------------------
  1333. RIP_BEZIER
  1334. ---------------------------------------------------------------------
  1335.          Function:  Draw a bezier curve
  1336.             Level:  0
  1337.           Command:  Z
  1338.         Arguments:  x1:2 y1:2 x2:2 y2:2 x3:2 y3:2 x4:2 y4:2 cnt:2
  1339.            Format:  !|Z <x1> <y1> <x2> <y2> <x3> <y3> <x4> <y4> <cnt>
  1340.           Example:  !|Z0A0B0C0D0E0F0G0H1G
  1341.   Uses Draw Color:  YES
  1342. Uses Line Pattern:  YES
  1343.   Uses Line Thick:  YES
  1344.   Uses Fill Color:  NO
  1345. Uses Fill Pattern:  NO
  1346.   Uses Write Mode:  YES
  1347.   Uses Font Sizes:  NO
  1348.     Uses Viewport:  YES                                               > v1.54
  1349.  
  1350. This command provides customizable curves.  Four control points are
  1351. used to create the shape of the curve.  The curves beginning point is
  1352. at point (x1,y1) and it ends at (x4,y4).  Points (x2,y2) and (x3,y3)
  1353. are not necessarily on the curve, but are used to pull the curve in
  1354. their direction.  The diagram below indicates how points 2 and 3 can
  1355. be utilized to form the desired curve.  Note that points 2 and 3 are
  1356. not actually on the curve, but points 1 and 4 are.
  1357.  
  1358.                           X2
  1359.  
  1360.                          *****
  1361.                        **     ****
  1362.                       *           **            X4
  1363.                      *              **          *
  1364.                    X1                 *       **
  1365.                                        *    **
  1366.                                         ****
  1367.  
  1368.                                          X3
  1369.  
  1370. NOTE: Points 2 and 3 are not actually on the curve - points 1 and 4
  1371.       are.
  1372.  
  1373. The last parameter of this command is the <cnt> parameter.  This
  1374. determines how many "segments" the curve should be drawn in.  Each
  1375. segment is in fact, a straight line.  The more segments you allow,
  1376. the smoother the curve may be.  If a curve does not have a
  1377. significant amount of "curviness" then a low "count" can improve
  1378. performance of the curve drawing.  Bezier Curves use "floating point"
  1379. math internally for its processing.  All parameters specified for
  1380. this command are simple integers however.
  1381.  
  1382. Each segment of the Bezier Curve will be drawn using the current      > v1.54
  1383. line style pattern and thickness.  You can achieve some unusual       > v1.54
  1384. effects using patterned lines for Bezier Curves.  If XOR is active    > v1.54
  1385. when you draw a bezier curve, you will find gaps at the inter-        > v1.54
  1386. sections of each segment.                                             > v1.54
  1387.  
  1388. NOTE: This command is implemented in C using double floating point    > v1.54
  1389.       numbers.  To make sure you do not have round-off or precision   > v1.54
  1390.       errors in another language, you should also use an equivalent   > v1.54
  1391.       floating point type.  In Borland's Turbo Pascal, do not use     > v1.54
  1392.       REAL's, but use DOUBLE's instead!                               > v1.54
  1393.  
  1394.  
  1395.  
  1396. ---------------------------------------------------------------------
  1397. RIP_POLYGON
  1398. ---------------------------------------------------------------------
  1399.          Function:  Draw polygon in current color/line-style
  1400.             Level:  0
  1401.           Command:  P
  1402.         Arguments:  npoints:2, x1:2, y1:2, ... xn:2, yn:2
  1403.            Format:  !|P <npoints> <x1> <y1> ... <xn> <yn>
  1404.           Example:  !|P03010105090905
  1405.   Uses Draw Color:  YES
  1406. Uses Line Pattern:  YES
  1407.   Uses Line Thick:  YES
  1408.   Uses Fill Color:  NO
  1409. Uses Fill Pattern:  NO
  1410.   Uses Write Mode:  YES
  1411.   Uses Font Sizes:  NO
  1412.     Uses Viewport:  YES                                               > v1.54
  1413.  
  1414. This command will draw a multi-sided closed polygon.  The polygon is
  1415. drawn using the current drawing color, line pattern and thickness.
  1416. The <npoints> parameter is between 2 and 512 and indicates how many
  1417. (x,y) coordinate pairs will follow, which is also the number of sides
  1418. of the polygon.  The polygon interior is not filled by RIP_POLYGON.
  1419.  
  1420. The polygon is enclosed by the last vertex between xn,yn and x1,y1.
  1421. In other words, you do not have to connect the end to the beginning -
  1422. it is automatically done for you.
  1423.  
  1424.  
  1425.  
  1426. ---------------------------------------------------------------------
  1427. RIP_FILL_POLYGON
  1428. ---------------------------------------------------------------------
  1429.          Function:  Draw filled polygon in current color/fill pattern
  1430.             Level:  0
  1431.           Command:  p
  1432.         Arguments:  npoints:2, x1:2, y1:2, ... xn:2, yn:2
  1433.            Format:  !|p <npoints> <x1> <y1> ... <xn> <yn>
  1434.           Example:  !|p03010105050909
  1435.   Uses Draw Color:  YES
  1436. Uses Line Pattern:  YES
  1437.   Uses Line Thick:  YES
  1438.   Uses Fill Color:  YES
  1439. Uses Fill Pattern:  YES
  1440.   Uses Write Mode:  YES
  1441.   Uses Font Sizes:  NO
  1442.     Uses Viewport:  YES                                               > v1.54
  1443.  
  1444. This command is identical to RIP_POLYGON, except that the interior of
  1445. the polygon is filled with the current fill color and fill pattern.
  1446. The actual outline of the polygon is drawn using the current drawing
  1447. color, line pattern and thickness.
  1448.  
  1449. NOTE:  You will get unusual effects if the lines of the polygon
  1450.        overlap, creating a polygon with internal "gaps".  (The rule
  1451.        is this: regions that are "inside" the polygon an even number
  1452.        of times due to overlap are NOT filled.)  The interior fill
  1453.        does not utilize Write Mode, but the outline of the polygon
  1454.        does.
  1455.  
  1456.  
  1457.  
  1458. --------------------------------------------------------------------- > v1.54
  1459. RIP_POLYLINE                                                          > v1.54
  1460. --------------------------------------------------------------------- > v1.54
  1461.          Function:  Draw a Poly-Line (multi-faceted line)             > v1.54
  1462.             Level:  0                                                 > v1.54
  1463.           Command:  l                                                 > v1.54
  1464.         Arguments:  npoints:2, x1:2, y1:2, ... xn:2, yn:2             > v1.54
  1465.            Format:  !|l <npoints> <x1> <y1> ... <xn> <yn>             > v1.54
  1466.           Example:  !|l03010105090905                                 > v1.54
  1467.   Uses Draw Color:  YES                                               > v1.54
  1468. Uses Line Pattern:  YES                                               > v1.54
  1469.   Uses Line Thick:  YES                                               > v1.54
  1470.   Uses Fill Color:  NO                                                > v1.54
  1471. Uses Fill Pattern:  NO                                                > v1.54
  1472.   Uses Write Mode:  YES                                               > v1.54
  1473.   Uses Font Sizes:  NO                                                > v1.54
  1474.     Uses Viewport:  YES                                               > v1.54
  1475.                                                                       > v1.54
  1476. This command will draw a multi-faceted line.  It is identical in      > v1.54
  1477. nature to the RIP_POLYGON command above, except that the last point   > v1.54
  1478. is NOT connected to the first point.  Generally speaking, a Poly-     > v1.54
  1479. Line is not an "enclosed area".  It should not be filled unless       > v1.54
  1480. you are very careful to close the shape so that it leaves a fillable  > v1.54
  1481. area.  The segments of the Poly-Line are drawn using the current      > v1.54
  1482. drawing color, line pattern, thickness and Drawing Write Mode.        > v1.54
  1483.                                                                       > v1.54
  1484. The <npoints> parameter is between 2 and 512 and indicates how many   > v1.54
  1485. (x,y) coordinate pairs will follow, which is also the number of sides > v1.54
  1486. of the Poly-Line.                                                     > v1.54
  1487.                                                                       > v1.54
  1488. An example of a five sided (6 vertices) Poly-Line might be:           > v1.54
  1489.                                                                       > v1.54
  1490.                X                 P4         X                         > v1.54
  1491.              P1 \                  X       / P6                       > v1.54
  1492.                  \                /|      /                           > v1.54
  1493.                   \              / |     /                            > v1.54
  1494.                    \            /  |    /                             > v1.54
  1495.                     \          /   |   /                              > v1.54
  1496.                      X--------X    |  /                               > v1.54
  1497.                    P2       P3     | /                                > v1.54
  1498.                                  P5|/                                 > v1.54
  1499.                                    X                                  > v1.54
  1500.                                                                       > v1.54
  1501.  
  1502.  
  1503. ---------------------------------------------------------------------
  1504. RIP_FILL
  1505. ---------------------------------------------------------------------
  1506.          Function:  Flood fill screen area with current fill settings
  1507.             Level:  0
  1508.           Command:  F
  1509.         Arguments:  x:2, y:2, border:2
  1510.            Format:  !|F <x> <y> <border>
  1511.           Example:  !|F25090F
  1512.   Uses Draw Color:  NO
  1513. Uses Line Pattern:  NO
  1514.   Uses Line Thick:  NO
  1515.   Uses Fill Color:  YES
  1516. Uses Fill Pattern:  YES
  1517.   Uses Write Mode:  NO
  1518.   Uses Font Sizes:  NO
  1519.     Uses Viewport:  YES                                               > v1.54
  1520.  
  1521. This command performs a "flood fill" emanating from the given <x,y>
  1522. point.  The fill "oozes" in all directions up to <border> color, but
  1523. the border itself is not changed.  Whatever is inside the border
  1524. that's not the border color gets changed to the current fill color
  1525. and fill pattern.  If the border color does not completely enclose
  1526. the <x,y> point, the fill will continue to the edges of the viewport.
  1527.  
  1528. If the point on the screen that is chosen as the "fill point" is the  > v1.54
  1529. same color as the fill border color, then no Fill Operation will be   > v1.54
  1530. performed!  This restriction is necessary because of some limitations > v1.54
  1531. of Flood Fill abilities in different hardware/software environments   > v1.54
  1532. like Microsoft Windows, etc).                                         > v1.54
  1533.  
  1534.  
  1535.  
  1536. ---------------------------------------------------------------------
  1537. RIP_LINE_STYLE
  1538. ---------------------------------------------------------------------
  1539.          Function:  Defines a line style and thickness
  1540.             Level:  0
  1541.           Command:  =
  1542.         Arguments:  style:2, user_pat:4, thick:2
  1543.            Format:  !|= <style> <user_pat> <thick>
  1544.           Example:  !|=01000001
  1545.   Uses Draw Color:  NO
  1546. Uses Line Pattern:  YES
  1547.   Uses Line Thick:  YES
  1548.   Uses Fill Color:  NO
  1549. Uses Fill Pattern:  NO
  1550.   Uses Write Mode:  NO
  1551.   Uses Font Sizes:  NO
  1552.     Uses Viewport:  NO                                                > v1.54
  1553.  
  1554. This command establishes the current line pattern and thickness for
  1555. many subsequent graphics primitive commands.  There are four built-in
  1556. line styles plus provisions for custom line patterns.
  1557.  
  1558.      Style   Description           Binary            Hex              > v1.54
  1559.      ----------------------------------------------------             > v1.54
  1560.      00      Normal, Solid Line    1111111111111111  FFFF             > v1.54
  1561.      01      Dotted Line           0011001100110011  3333             > v1.54
  1562.      02      Centered Line         0001111000111111  1E3F             > v1.54
  1563.      03      Dashed Line           0001111100011111  1F1F             > v1.54
  1564.      04      Custom Defined line (see about <user_pat> below)
  1565.  
  1566.      Thick   Description
  1567.      -------------------------------
  1568.      01      Lines are 1 pixel wide
  1569.      03      Lines are 3 pixels wide
  1570.  
  1571. If the <style> is set to a value of 4 (custom pattern), then the
  1572. <user_pat> parameter is used as a 16-bit representation of the pixels
  1573. in the line pattern.  For example:
  1574.  
  1575. Repeating Pattern     Binary Coding     Hex     Decimal   MegaNum
  1576. -------------------------------------------------------------------
  1577.  - - - - - - - -    1010101010101010    AAAA     43690     0XPM
  1578.  ----    ----       1111000011110000    F0F0     61680     1BLC
  1579.  
  1580. So, the most-significant-bit of <user_pat> is toward the starting
  1581. point of the line or border that uses this fill pattern.  If the
  1582. <style> parameter is not 4, then the <user_pat> parameter is ignored.
  1583.  
  1584.  
  1585.  
  1586. ---------------------------------------------------------------------
  1587. RIP_FILL_STYLE
  1588. ---------------------------------------------------------------------
  1589.          Function:  Set current fill style (predefined) & fill color
  1590.             Level:  0
  1591.           Command:  S
  1592.         Arguments:  pattern:2, color:2
  1593.            Format:  !|S <pattern> <color>
  1594.           Example:  !|S050F
  1595.   Uses Draw Color:  NO
  1596. Uses Line Pattern:  NO
  1597.   Uses Line Thick:  NO
  1598.   Uses Fill Color:  YES
  1599. Uses Fill Pattern:  YES
  1600.   Uses Write Mode:  NO
  1601.   Uses Font Sizes:  NO
  1602.     Uses Viewport:  NO                                                > v1.54
  1603.  
  1604. This command defines the current fill pattern and fill color for use
  1605. in subsequent graphics fill operations.  There are twelve (12)
  1606. predefined fill patterns.  They are:
  1607.  
  1608.     Pattern  Description                 Example       Misc
  1609.     -----------------------------------------------------------------
  1610.       00     Fill with background color                (color #0)
  1611.       01     Solid Fill                                (fill color)
  1612.       02     Line Fill                   -----------   (thick lines)
  1613.       03     Light Slash Fill            /  /  /  /    (thin lines)
  1614.       04     Normal Slash Fill           // // // //   (thick lines)
  1615.       05     Normal Backslash Fill       \\ \\ \\ \\   (thick lines)
  1616.       06     Light Backslash Fill        \  \  \  \    (thin lines)
  1617.       07     Light Hatch Fill            ###########   (thin lines)
  1618.       08     Heavy Cross Hatch Fill      XXXXXXXXXXX   (thin lines)
  1619.       09     Interleaving Line Fill      +-+-+-+-+-+   (thin lines)
  1620.       0A     Widely spaced dot fill      . : . : . :   (pixels only)
  1621.       0B     Closely spaced dot fill     :::::::::::   (pixels only)
  1622.  
  1623. The <color> parameter is the fill color for subsequent fill commands.
  1624. The "active" pixels of the pattern become this color.  The "inactive"
  1625. pixels become the current background color (color 00, typically
  1626. black).  Fill pattern 00 will set the entire fill area to the
  1627. background color.  (In this special case, the fill color doesn't
  1628. matter.)
  1629.  
  1630. The following twelve diagrams show visually what each fill pattern    > v1.54
  1631. appears like.  Next to each diagram are the eight numerical values    > v1.54
  1632. which represent the monochrome bit-pattern of each line of each       > v1.54
  1633. pattern.  Numbers are shown in Hexadecimal (base 16), decimal (base   > v1.54
  1634. 10) and MegaNum (base 36):                                            > v1.54
  1635.                                                                       > v1.54
  1636.                                                                       > v1.54
  1637.        BACKGROUND FILL                      SOLID FILL                > v1.54
  1638.                                                                       > v1.54
  1639.      --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
  1640.     |        |  00    0  00          |########|  FF  255  73          > v1.54
  1641.     |        |  00    0  00          |########|  FF  255  73          > v1.54
  1642.     |        |  00    0  00          |########|  FF  255  73          > v1.54
  1643.     |        |  00    0  00          |########|  FF  255  73          > v1.54
  1644.     |        |  00    0  00          |########|  FF  255  73          > v1.54
  1645.     |        |  00    0  00          |########|  FF  255  73          > v1.54
  1646.     |        |  00    0  00          |########|  FF  255  73          > v1.54
  1647.     |        |  00    0  00          |########|  FF  255  73          > v1.54
  1648.      --------                         --------                        > v1.54
  1649.         00                               01                           > v1.54
  1650.                                                                       > v1.54
  1651.                                                                       > v1.54
  1652.                                                                       > v1.54
  1653.            LINE FILL                     LIGHT SLASH FILL             > v1.54
  1654.                                                                       > v1.54
  1655.      --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
  1656.     |########|  FF  255  73          |       #|  01    1  01          > v1.54
  1657.     |########|  FF  255  73          |      # |  02    2  02          > v1.54
  1658.     |        |  00    0  00          |     #  |  04    4  04          > v1.54
  1659.     |        |  00    0  00          |    #   |  08    8  08          > v1.54
  1660.     |########|  FF  255  73          |   #    |  10   16  0G          > v1.54
  1661.     |########|  FF  255  73          |  #     |  20   32  0W          > v1.54
  1662.     |        |  00    0  00          | #      |  40   64  1S          > v1.54
  1663.     |        |  00    0  00          |#       |  80  128  3K          > v1.54
  1664.      --------                         --------                        > v1.54
  1665.         02                               03                           > v1.54
  1666.                                                                       > v1.54
  1667.                                                                       > v1.54
  1668.                                                                       > v1.54
  1669.                                                                       > v1.54
  1670.         NORMAL SLASH FILL               LIGHT BACKSLASH FILL          > v1.54
  1671.                                                                       > v1.54
  1672.      --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
  1673.     |###     |  E0  224  68          |####    |  F0  240  60          > v1.54
  1674.     |##     #|  C1  193  5D          | ####   |  78  120  3C          > v1.54
  1675.     |#     ##|  83  131  3N          |  ####  |  3C   60  1O          > v1.54
  1676.     |     ###|  07    7  07          |   #### |  1E   30  0U          > v1.54
  1677.     |    ### |  0E   15  0F          |    ####|  0F   15  0F          > v1.54
  1678.     |   ###  |  1C   28  0S          |#    ###|  87  135  3R          > v1.54
  1679.     |  ###   |  38   56  1K          |##    ##|  C3  195  5F          > v1.54
  1680.     | ###    |  70  112  34          |###    #|  E1  225  69          > v1.54
  1681.      --------                         --------                        > v1.54
  1682.         04                               05                           > v1.54
  1683.                                                                       > v1.54
  1684.                                                                       > v1.54
  1685.                                                                       > v1.54
  1686.                                                                       > v1.54
  1687.       LIGHT BACKSLASH FILL               LIGHT HATCH FILL             > v1.54
  1688.                                                                       > v1.54
  1689.      --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
  1690.     |# #  # #|  A5  165  4L          |########|  FF  255  73          > v1.54
  1691.     |## #  # |  D2  210  5U          |#   #   |  88  136  3S          > v1.54
  1692.     | ## #  #|  69  105  2X          |#   #   |  88  136  3S          > v1.54
  1693.     |# ## #  |  B4  180  50          |#   #   |  88  136  3S          > v1.54
  1694.     | # ## # |  5A   90  2I          |########|  FF  255  73          > v1.54
  1695.     |  # ## #|  2D   45  19          |#   #   |  88  136  3S          > v1.54
  1696.     |#  # ## |  96  150  46          |#   #   |  88  136  3S          > v1.54
  1697.     | #  # ##|  4B   75  23          |#   #   |  88  136  3S          > v1.54
  1698.      --------                         --------                        > v1.54
  1699.         06                               07                           > v1.54
  1700.                                                                       > v1.54
  1701.                                                                       > v1.54
  1702.                                                                       > v1.54
  1703.                                                                       > v1.54
  1704.      HEAVY CROSS HATCH FILL           INTERLEAVING LINE FILL          > v1.54
  1705.                                                                       > v1.54
  1706.      --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
  1707.     |#      #|  81  129  3L          |##  ##  |  CC  204  5O          > v1.54
  1708.     | #    # |  42   66  1U          |  ##  ##|  33   51  1F          > v1.54
  1709.     |  #  #  |  24   36  10          |##  ##  |  CC  204  5O          > v1.54
  1710.     |   ##   |  18   24  0O          |  ##  ##|  33   51  1F          > v1.54
  1711.     |   ##   |  18   24  0O          |##  ##  |  CC  204  5O          > v1.54
  1712.     |  #  #  |  24   36  10          |  ##  ##|  33   51  1F          > v1.54
  1713.     | #    # |  42   66  1U          |##  ##  |  CC  204  5O          > v1.54
  1714.     |#      #|  81  129  3L          |  ##  ##|  33   51  1F          > v1.54
  1715.      --------                         --------                        > v1.54
  1716.         08                               09                           > v1.54
  1717.                                                                       > v1.54
  1718.                                                                       > v1.54
  1719.                                                                       > v1.54
  1720.                                                                       > v1.54
  1721.      WIDELY SPACED DOT FILL           CLOSELY SPACED DOT FILL         > v1.54
  1722.                                                                       > v1.54
  1723.      --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
  1724.     |#       |  80  128  3K          |#   #   |  88  136  3S          > v1.54
  1725.     |        |  00    0  00          |        |  00    0  00          > v1.54
  1726.     |    #   |  08    8  08          |  #   # |  22   34  0Y          > v1.54
  1727.     |        |  00    0  00          |        |  00    0  00          > v1.54
  1728.     |#       |  80  128  3K          |#   #   |  88  136  3S          > v1.54
  1729.     |        |  00    0  00          |        |  00    0  00          > v1.54
  1730.     |    #   |  08    8  08          |  #   # |  22   34  0Y          > v1.54
  1731.     |        |  00    0  00          |        |  00    0  00          > v1.54
  1732.      --------                         --------                        > v1.54
  1733.         0A                               0B                           > v1.54
  1734.  
  1735.  
  1736.  
  1737. ---------------------------------------------------------------------
  1738. RIP_FILL_PATTERN
  1739. ---------------------------------------------------------------------
  1740.          Function:  Set user-definable (custom) fill pattern/color
  1741.             Level:  0
  1742.           Command:  s
  1743.         Arguments:  c1:2 c2:2 c3:2 c4:2 c5:2 c6:2 c7:2 c8:2 col:2
  1744.            Format:  !|s <c1> <c2> <c3> <c4> <c5> <c6> <c7> <c8> <col>
  1745.           Example:  !|s11223344556677880F
  1746.   Uses Draw Color:  NO
  1747. Uses Line Pattern:  NO
  1748.   Uses Line Thick:  NO
  1749.   Uses Fill Color:  YES
  1750. Uses Fill Pattern:  YES
  1751.   Uses Write Mode:  NO
  1752.   Uses Font Sizes:  NO
  1753.     Uses Viewport:  NO                                                > v1.54
  1754.  
  1755. This command allows you to specify a user-defined, custom Fill
  1756. Pattern.  This pattern supersedes the predefined patterns of
  1757. RIP_FILL_STYLE.  A custom fill pattern is an 8x8 pixel array defining
  1758. which pixels should be drawn in the current fill color (as set by the
  1759. <col> parameter here).  The other pixels in the fill area are set to
  1760. the current background color (color 00, typically black).
  1761.  
  1762. Each of the eight parameters of this command, <c1> through <c8>
  1763. represent bit-patterns for a line of the 8x8 pixel array.  Each line
  1764. is comprised of 8 pixels.  The value of each parameter is the binary
  1765. representation of these 8 pixels as follows:
  1766.  
  1767.      Bit     7     6    5    4   3   2   1   0
  1768.      ----------------------------------------------
  1769.      c1     128   64   32   16   8   4   2   1
  1770.      c2     128   64   32   16   8   4   2   1
  1771.      c3     128   64   32   16   8   4   2   1
  1772.      c4     128   64   32   16   8   4   2   1
  1773.      c5     128   64   32   16   8   4   2   1
  1774.      c6     128   64   32   16   8   4   2   1
  1775.      c7     128   64   32   16   8   4   2   1
  1776.      c8     128   64   32   16   8   4   2   1
  1777.  
  1778. So, c1 is the top, and the most-significant bit is to the left.
  1779.  
  1780. NOTE:  The RIP_FILL_STYLE (predefined fill patterns) and this
  1781.        RIP_FILL_PATTERN (custom fill patterns) completely override
  1782.        each other's effects.
  1783.  
  1784.  
  1785.  
  1786. ---------------------------------------------------------------------
  1787. RIP_MOUSE
  1788. ---------------------------------------------------------------------
  1789.          Function:  Defines a rectangular hot mouse region
  1790.             Level:  1
  1791.           Command:  M
  1792.         Arguments:  num:2 x0:2 y0:2 x1:2 y1:2 clk:1 clr:1 res:5 text
  1793.            Format:  !|1M <num> <x0><y0><x1><y1> <clk><clr><res><text>
  1794.           Example:  !|1M00001122331100000host command^M
  1795.   Uses Draw Color:  NO
  1796. Uses Line Pattern:  NO
  1797.   Uses Line Thick:  NO
  1798.   Uses Fill Color:  NO
  1799. Uses Fill Pattern:  NO
  1800.   Uses Write Mode:  NO
  1801.   Uses Font Sizes:  NO
  1802.     Uses Viewport:  YES                                               > v1.54
  1803.  
  1804. This command ties together three things:
  1805.  
  1806.      A region on the screen
  1807.      A mouse-click event
  1808.      A string of text to be transmitted by the terminal.
  1809.  
  1810. This command defines a rectangular region on the screen that functions
  1811. as a "hot" mouse area.  If the user clicks the [left] mouse button
  1812. while pointing inside the region, then the terminal must transmit the
  1813. <text> string to the Host.  The (x0,y0) parameter MUST be the
  1814. upper-left corner, and (x1,y1) MUST be the lower-right corner of the
  1815. region.
  1816.  
  1817. The <num> parameter used to be used in the older RIPscrip v1.0        > v1.54
  1818. specification but is now obsolete.  For upwards compatibility, it     > v1.54
  1819. should be set to "00".                                                > v1.54
  1820.  
  1821. The <clk> parameter, if 1, indicates that the region should be
  1822. visibly inverted while the mouse button is down.  This offers visual
  1823. feedback. If <clk> is 0, the region will not be inverted while
  1824. clicked.
  1825.  
  1826. The <clr> parameter, if 1, will physically zoom the text window to
  1827. full screen size and clear the screen.  This is useful if the <text>
  1828. parameter instructs the host to enter an area of the System that
  1829. doesn't support RIPscrip graphics.
  1830.  
  1831. The <text> parameter is a Host command that gets sent when the field
  1832. is clicked.  You may use a caret (^) to represent control characters,
  1833. (e.g., ^M for carriage return, ^G, ^C, etc.).
  1834.  
  1835. When this command is stored in-memory, it is converted to global      > v1.54
  1836. screen coordinates (for internal storage only).  This makes it so     > v1.54
  1837. that if you have mouse regions defined in multiple different          > v1.54
  1838. viewports, that each field will be properly inverted at the right     > v1.54
  1839. location regardless of the currently defined viewport.                > v1.54
  1840.  
  1841. NOTE: All Mouse Fields are scanned in "last in, first out" order.     > v1.54
  1842.       This means that the last-most received Mouse Field will be      > v1.54
  1843.       the first one scanned for a mouse click.                        > v1.54
  1844.  
  1845. NOTE:  You are limited to a maximum of 128 Mouse Regions or           > v1.54
  1846.        Mouse Buttons (128 total).                                     > v1.54
  1847.  
  1848.        In addition, the 5-byte <res> parameter is RESERVED FOR
  1849.        FUTURE USE, and should be set to zeros (00000).
  1850.  
  1851.  
  1852.  
  1853. ---------------------------------------------------------------------
  1854. RIP_KILL_MOUSE_FIELDS
  1855. ---------------------------------------------------------------------
  1856.          Function:  Destroys all previously defined hot mouse regions
  1857.             Level:  1
  1858.           Command:  K
  1859.         Arguments:  <none>
  1860.            Format:  !|1K
  1861.           Example:  !|1K
  1862.   Uses Draw Color:  NO
  1863. Uses Line Pattern:  NO
  1864.   Uses Line Thick:  NO
  1865.   Uses Fill Color:  NO
  1866. Uses Fill Pattern:  NO
  1867.   Uses Write Mode:  NO
  1868.   Uses Font Sizes:  NO
  1869.     Uses Viewport:  NO                                                > v1.54
  1870.  
  1871. This command will "forget" all Mouse Regions.  Use it at the beginning
  1872. of each Scene, so that one scene's Mouse Regions don't get used in
  1873. another.
  1874.  
  1875.  
  1876.  
  1877. ---------------------------------------------------------------------
  1878. RIP_BEGIN_TEXT
  1879. ---------------------------------------------------------------------
  1880.          Function:  Define a rectangular text region
  1881.             Level:  1
  1882.           Command:  T
  1883.         Arguments:  x1:2, y1:2, x2:2, y2:2, res:2
  1884.            Format:  !|1T <x1> <y1> <x2> <y2> <res>
  1885.           Example:  !|1T00110011
  1886.   Uses Draw Color:  NO
  1887. Uses Line Pattern:  NO
  1888.   Uses Line Thick:  NO
  1889.   Uses Fill Color:  NO
  1890. Uses Fill Pattern:  NO
  1891.   Uses Write Mode:  NO
  1892.   Uses Font Sizes:  NO
  1893.     Uses Viewport:  YES                                               > v1.54
  1894.  
  1895. This command defines a rectangular portion of the graphics viewport
  1896. that is to display text, usually a long stream of text.  Following
  1897. this command should be a number of RIP_REGION_TEXT commands with the
  1898. text to be displayed.  The RIP_END_TEXT terminates this stream of
  1899. text, something like this:
  1900.  
  1901. RIP_BEGIN_TEXT
  1902.      RIP_REGION_TEXT
  1903.      RIP_REGION_TEXT
  1904.      RIP_REGION_TEXT
  1905.      :
  1906.      RIP_REGION_TEXT
  1907. RIP_END_TEXT
  1908.  
  1909. There must be at least one RIP_REGION_TEXT command in between the
  1910. header and the footer.  There may be as many as needed.
  1911.  
  1912. These commands ignore the current font "direction"; all text is
  1913. always displayed horizontally.
  1914.  
  1915. NOTE:  The "res" parameter is two bytes wide and is RESERVED for
  1916.        future use.
  1917.  
  1918.  
  1919.  
  1920. ---------------------------------------------------------------------
  1921. RIP_REGION_TEXT
  1922. ---------------------------------------------------------------------
  1923.          Function:  Display a line of text in rectangular text region
  1924.             Level:  1
  1925.           Command:  t
  1926.         Arguments:  justify:1 and text-string
  1927.            Format:  !|1t <justify> <text-string>
  1928.           Example:  !|1t1This is a text line to be justified
  1929.   Uses Draw Color:  YES
  1930. Uses Line Pattern:  NO
  1931.   Uses Line Thick:  NO
  1932.   Uses Fill Color:  NO
  1933. Uses Fill Pattern:  NO
  1934.   Uses Write Mode:  YES
  1935.   Uses Font Sizes:  YES
  1936.     Uses Viewport:  YES                                               > v1.54
  1937.  
  1938. A number of these commands may come sandwiched between the
  1939. RIP_BEGIN_TEXT and RIP_END_TEXT commands.  The <text-string> is
  1940. already word-wrapped in such a way that it will fit inside the
  1941. rectangular region based on the current font, font size, and drawing
  1942. color.
  1943.  
  1944. There are two possible settings for the <justify> parameter:
  1945.  
  1946.   Justify   Description
  1947.   ------------------------------------------------------------------
  1948.     0       Don't right/left justify.  Left-justify only
  1949.     1       Perform right/left margin justification of this line of
  1950.             text.
  1951.  
  1952. If a text line falls off the bottom of the region, it is discarded --
  1953. the rectangular Text Region does not scroll.
  1954.  
  1955. This command is intended to import some sort of text file document    > v1.54
  1956. directly into a RIPscrip scene and format it nicely to fit inside a   > v1.54
  1957. simple rectangular area.  If the <justify> parameter is set to a      > v1.54
  1958. value of "1" for a given RIP_REGION_TEXT line, then that line will be > v1.54
  1959. justified to both the left and right margins (the RIP_BEGIN_TEXT      > v1.54
  1960. boundaries).  This is so that the displayed text aligns on both sides > v1.54
  1961. with the invisible boundaries.  This "justification" is done by       > v1.54
  1962. splitting each RIP_REGION_TEXT line up into chunks of word-groups,    > v1.54
  1963. broken up at their "white-space" locations.  Each spacer is then      > v1.54
  1964. padded by however many pixels are necessary to keep each spacer       > v1.54
  1965. uniformly of approximately equal size.  Only enough spare pixels are  > v1.54
  1966. added to make sure that the right-edge of the text region alignts     > v1.54
  1967. with the right border of the boundary.  The result is a nicely        > v1.54
  1968. formatted text block.                                                 > v1.54
  1969.  
  1970.  
  1971. ---------------------------------------------------------------------
  1972. RIP_END_TEXT
  1973. ---------------------------------------------------------------------
  1974.          Function:  End a rectangular text region
  1975.             Level:  1
  1976.           Command:  E
  1977.         Arguments:  <none>
  1978.            Format:  !|1E
  1979.           Example:  !|1E
  1980.   Uses Draw Color:  NO
  1981. Uses Line Pattern:  NO
  1982.   Uses Line Thick:  NO
  1983.   Uses Fill Color:  NO
  1984. Uses Fill Pattern:  NO
  1985.   Uses Write Mode:  NO
  1986.   Uses Font Sizes:  NO
  1987.     Uses Viewport:  YES                                               > v1.54
  1988.  
  1989. This command indicates the end of a formatted text block.  Only one
  1990. of these "end" commands is necessary for each block.
  1991.  
  1992.  
  1993.  
  1994. ---------------------------------------------------------------------
  1995. RIP_GET_IMAGE
  1996. ---------------------------------------------------------------------
  1997.          Function:  Copy rectangular image to clipboard (as icon)
  1998.             Level:  1
  1999.           Command:  C
  2000.         Arguments:  x0:2, y0:2, x1:2, y1:2, res:1
  2001.            Format:  !|1C <x0> <y0> <x1> <y1> <res>
  2002.           Example:  !|1C001122330
  2003.   Uses Draw Color:  NO
  2004. Uses Line Pattern:  NO
  2005.   Uses Line Thick:  NO
  2006.   Uses Fill Color:  NO
  2007. Uses Fill Pattern:  NO
  2008.   Uses Write Mode:  NO
  2009.   Uses Font Sizes:  NO
  2010.     Uses Viewport:  YES                                               > v1.54
  2011.  
  2012. This command instructs the terminal program to copy the rectangular
  2013. region defined by (x0,y0) to (x1,y1) onto an internal Clipboard for
  2014. future use.  This combined with the Paste Clipboard command can
  2015. provide an extremely powerful and efficient mechanism to avoid
  2016. baud-rate bandwidth limitations.  The (x0,y0) parameter MUST specify
  2017. the upper-left corner of the region and the (x1,y1) parameter MUST
  2018. specify the lower-right corner.  If the indicated coordinates are in
  2019. anyway invalid, the command is ignored.  The Clipboard is completely
  2020. overwritten by this command (the previous contents are lost).
  2021.  
  2022. NOTE:  The <res> parameter is RESERVED FOR FUTURE USE and
  2023.        should be set to zero.
  2024.  
  2025.  
  2026.  
  2027. ---------------------------------------------------------------------
  2028. RIP_PUT_IMAGE
  2029. ---------------------------------------------------------------------
  2030.          Function:  Pastes the clipboard contents onto the screen
  2031.             Level:  1
  2032.           Command:  P
  2033.         Arguments:  x:2, y:2, mode:2, res:1
  2034.            Format:  !|1P <x> <y> <mode> <res>
  2035.           Example:  !|1P0011010
  2036.   Uses Draw Color:  NO
  2037. Uses Line Pattern:  NO
  2038.   Uses Line Thick:  NO
  2039.   Uses Fill Color:  NO
  2040. Uses Fill Pattern:  NO
  2041.   Uses Write Mode:  NO
  2042.   Uses Font Sizes:  NO
  2043.     Uses Viewport:  YES                                               > v1.54
  2044.  
  2045. This command takes the contents of the Clipboard (if any) and pastes
  2046. the image onto the screen starting at the upper-left corner of the
  2047. image of (x,y).  If the right edge of the image would go off-screen,
  2048. the paste command is ignored.  The Height and Width of the clipboard
  2049. image is recorded on the Clipboard, so this command doesn't need to
  2050. supply it.
  2051.  
  2052. The <mode> parameter defines "how" the image will be pasted on the
  2053. screen:
  2054.  
  2055.   Mode   Description                                          Logical
  2056.   -------------------------------------------------------------------
  2057.    00    Paste the image on-screen normally                   (COPY)
  2058.    01    Exclusive-OR  image with the one already on screen   (XOR)
  2059.    02    Logically OR  image with the one already on screen   (OR)
  2060.    03    Logically AND image with the one already on screen   (AND)
  2061.    04    Paste the inverse of the image on the screen         (NOT)
  2062.  
  2063. NOTE:  The 1-byte <res> parameter is RESERVED FOR FUTURE USE
  2064.        and should be set to zero.
  2065.  
  2066.  
  2067.  
  2068. ---------------------------------------------------------------------
  2069. RIP_WRITE_ICON
  2070. ---------------------------------------------------------------------
  2071.          Function:  Write contents of the clipboard (icon) to disk
  2072.             Level:  1
  2073.           Command:  W
  2074.         Arguments:  res:1, filename
  2075.            Format:  !|1W <res> <filename>
  2076.           Example:  !|1W0filename.icn
  2077.   Uses Draw Color:  NO
  2078. Uses Line Pattern:  NO
  2079.   Uses Line Thick:  NO
  2080.   Uses Fill Color:  NO
  2081. Uses Fill Pattern:  NO
  2082.   Uses Write Mode:  NO
  2083.   Uses Font Sizes:  NO
  2084.     Uses Viewport:  NO                                                > v1.54
  2085.  
  2086. This command takes the contents of the Clipboard and writes it to a
  2087. disk file.  This Icon file can be loaded later with a RIP_LOAD_ICON
  2088. command and stamped on the screen.
  2089.  
  2090. The command instructs the terminal to store an Icon on the terminal's
  2091. disk drive, or on some appropriate storage media.  Path or
  2092. sub-directory information is not allowed in the filename portion of
  2093. the command.  If the clipboard is nonexistent (i.e., at the beginning
  2094. of a scene), this command is ignored.  If an Icon by the same name
  2095. already exists on disk, it is overwritten.
  2096.  
  2097. NOTE:  The <res> parameter is RESERVED FOR FUTURE USE and
  2098.        should be set to zero.
  2099.  
  2100.  
  2101.  
  2102. ---------------------------------------------------------------------
  2103. RIP_LOAD_ICON
  2104. ---------------------------------------------------------------------
  2105.          Function:  Loads and displays a disk-based icon to screen
  2106.             Level:  1
  2107.           Command:  I
  2108.         Arguments:  x:2, y:2, mode:2, clipboard:1, res:2, filename
  2109.            Format:  !|1I <x> <y> <mode> <clipboard> <res> <filename>
  2110.           Example:  !|1I001101010button.icn
  2111.   Uses Draw Color:  NO
  2112. Uses Line Pattern:  NO
  2113.   Uses Line Thick:  NO
  2114.   Uses Fill Color:  NO
  2115. Uses Fill Pattern:  NO
  2116.   Uses Write Mode:  NO
  2117.   Uses Font Sizes:  NO
  2118.     Uses Viewport:  YES                                               > v1.54
  2119.  
  2120. This command instructs the terminal to read an Icon from disk and
  2121. display it at the given upper-left (x,y) location.  If the width or
  2122. height of the Icon would make it go off the right or left edge of the
  2123. screen, the Icon will not be displayed.  The <mode> parameter defines
  2124. the modes in which the Icon will be displayed on the screen.  The
  2125. modes are identical to the RIP_PUT_IMAGE command, and are as follows:
  2126.  
  2127. The .ICN file extension does not need to be included as part of the
  2128. filename.  If omitted, it will automatically be appended to the
  2129. filename.  If an extension is provided, it will be used verbatim.
  2130.  
  2131.   Mode   Description                                         Logical
  2132.   ------------------------------------------------------------------
  2133.    00    Paste the image on-screen normally                   (COPY)
  2134.    01    Exclusive-OR  image with the one already on screen   (XOR)
  2135.    02    Logically OR  image with the one already on screen   (OR)
  2136.    03    Logically AND image with the one already on screen   (AND)
  2137.    04    Paste the inverse of the image on the screen         (NOT)
  2138.  
  2139. If the <clipboard> parameter is 1, then the image pasted on screen
  2140. AND also copied onto the Clipboard.  If 0, it is simply pasted on the
  2141. screen.
  2142.  
  2143. The <filename> parameter must not contain any sub-directory or path
  2144. information and must specify a valid Icon file name.  If the Icon
  2145. cannot be located or an error occurs on the disk, then a box should
  2146. be displayed on screen indicating that the given Icon File could not
  2147. be loaded.  This visual prompt indicates that something is amiss to
  2148. the end-user.
  2149.  
  2150. NOTE:  The 2-byte <res> parameter is RESERVED FOR THE FUTURE
  2151.        and unlike many other previously mentioned reserved
  2152.        parameters, should be set to "10".
  2153.  
  2154.  
  2155.  
  2156. ---------------------------------------------------------------------
  2157. RIP_BUTTON_STYLE
  2158. ---------------------------------------------------------------------
  2159.          Function:  Button style definition
  2160.             Level:  1
  2161.           Command:  B
  2162.         Arguments:  wid:2 hgt:2 orient:2 flags:4 size:2
  2163.                     dfore:2 dback:2 bright:2 dark:2 surface:2
  2164.                     grp_no:2 flags2:2 uline_col:2 corner_col:2
  2165.                     res:6
  2166.            Format:  !|1B <wid> <hgt> <orient> <flags>
  2167.                     <bevsize> <dfore> <dback> <bright> <dark>
  2168.                     <surface> <grp_no> <flags2> <uline_col>
  2169.                     <corner_col> <res>
  2170.           Example:  !|1B0A0A010274030F080F080700010E07000000
  2171.   Uses Draw Color:  NO
  2172. Uses Line Pattern:  NO
  2173.   Uses Line Thick:  NO
  2174.   Uses Fill Color:  NO
  2175. Uses Fill Pattern:  NO
  2176.   Uses Write Mode:  NO
  2177.   Uses Font Sizes:  NO
  2178.     Uses Viewport:  NO                                                > v1.54
  2179.  
  2180. This RIPscrip command is probably one of the most complex in the
  2181. entire protocol.  It defines how subsequent RIP_BUTTON commands will
  2182. be interpreted.  The purpose of this command is to define what a
  2183. Button is and how they operate.  Buttons can have many different
  2184. configurations, flags, and styles.  With the diversity of modes that
  2185. the Button can take on, complexity is a necessary evil.
  2186.  
  2187. This command does not actually do anything visibly on the screen.
  2188. Simply put, this creates an internal definition for the Button mode
  2189. which will be used with RIP_BUTTON commands after the definition is
  2190. created.
  2191.  
  2192. Every Button can have an optional text label.  It can appear in
  2193. several different locations compared to the Button itself.  This is
  2194. specified in the <orient> parameter.  The actual text of the label is
  2195. not specified with this command, it is specified when you actually
  2196. create a Button (see RIP_BUTTON below).  The value that <orient> can
  2197. be is as follows:
  2198.  
  2199.         Value   Description of Orientation
  2200.         -------------------------------------------------
  2201.          00     Display label above button
  2202.          01     Display label to the left of button
  2203.          02     Display label in the center of the button
  2204.          03     Display label to the right of button
  2205.          04     Display label beneath the button
  2206.  
  2207. There are three basic "types" of Buttons.  There are Icon buttons,    > v1.54
  2208. Clipboard buttons and Plain buttons.  Each of these differ in the     > v1.54
  2209. way that they create the button's image.  A description of each type  > v1.54
  2210. is as follows:                                                        > v1.54
  2211.                                                                       > v1.54
  2212.      ICON BUTTON (flag 128) - An Icon Button means that the           > v1.54
  2213.      actual image of the button will be created by loading a          > v1.54
  2214.      bitmap icon image from the disk and load it at the given         > v1.54
  2215.      locatino.  Any special effects (see below) can be applied        > v1.54
  2216.      to the Icon to further enhance the image.  The filename          > v1.54
  2217.      for the Icon is supplied with the RIP_BUTTON command, as         > v1.54
  2218.      is the Icon's upper left X/Y coordinate.  Icon Buttons           > v1.54
  2219.      are always stamped in COPY mode.                                 > v1.54
  2220.                                                                       > v1.54
  2221.      CLIPBOARD BUTTON (flag 1) - A clipboard button uses the          > v1.54
  2222.      current contents of the clipboard for the base image of          > v1.54
  2223.      the button.  If no clipboard is defined, then the button         > v1.54
  2224.      is ignored.  The clipboard is pasted in COPY mode at             > v1.54
  2225.      the X/Y location specified in the RIP_BUTTON command             > v1.54
  2226.      that defines the actual button instance.  Any special            > v1.54
  2227.      effects can be applied to this image to further enhance          > v1.54
  2228.      the overall button's image.                                      > v1.54
  2229.                                                                       > v1.54
  2230.      PLAIN BUTTON (flag 256) - A plain button is exactly that,        > v1.54
  2231.      plain.  No special graphics are used to create the button.       > v1.54
  2232.      The entire button region is simply filled-in with a solid        > v1.54
  2233.      colored rectangle using the <surface> color.  Any                > v1.54
  2234.      special effects can be further applied to enhance the            > v1.54
  2235.      button's appearance.                                             > v1.54
  2236.  
  2237. The <hgt> and <wid> parameters represent the fixed height and width
  2238. of the Button (applies only to Plain Buttons).  If both values are
  2239. greater than zero, then this will represent the actual size of the
  2240. Button (its dimensions are not specified by the RIP_BUTTON command).
  2241. If both of these are set to zero, then the actual RIP_BUTTON command
  2242. will specify the size of the particular Button (dynamic sizing).
  2243.  
  2244. The <bevsize> parameter is only used if the BEVEL FLAG (flag 512) is  > v1.54
  2245. specified.  When active, this parameter will determine how many
  2246. pixels thick the bevel should be.  This may be any value greater or
  2247. equal to zero.
  2248.  
  2249. There are a large number of flag values that can be combined to
  2250. achieve a great many effects.  There are two flag parameters for the
  2251. RIP_BUTTON_STYLE command, <flags> and <flags2>.  They are detailed in
  2252. the two tables that follow in this Section.  You may combine any of
  2253. the flags in the first table together simply by adding the "Value" of
  2254. each one together and representing that number as a MegaNum.
  2255.  
  2256. The <dfore> and <dback> parameters are used with the text label.  The
  2257. <dfore> parameter is the foreground color for the text.  It is always
  2258. used to determine the color of the text label.  The <dback> color is
  2259. the color of the dropshadow (if any).  This parameter is only used
  2260. when you have specified the "Dropshadow" flag in the <flags>
  2261. parameter (see below).
  2262.  
  2263. The <bright>, <dark> and <surface> parameters are used with Plain
  2264. Buttons and with the Special Effects styles (see <flags> below).
  2265. These colors represent the highlighted color, the shadowed color, and
  2266. the regular surface color that is used in Special Effects.  Typical
  2267. color combinations for these colors might be White, Dark-Gray and
  2268. Light-Gray respectively for a "chiseled steel" appearance.  Each of
  2269. these values can contain a two-digit value representing any valid
  2270. color code that may be used in the RIP_COLOR command.
  2271.  
  2272. In addition to the special effects colors, are two additional colors
  2273. that can be used, <uline_color> which is used for the color of the
  2274. underline (in the text label), and <corner_color> which is used to
  2275. display the colors of corners for things like the Bevel, Recess, etc.
  2276.  
  2277. The <grp_no> parameter determines which Button Group subsequent
  2278. RIP_BUTTON commands will be associated with.  Button Groups are used
  2279. to maintain groups of Buttons for things like Radio Buttons and/or
  2280. Checkbox Buttons.  See the section on the BUTTON COMMAND for more
  2281. information on these modes, and what Button Groups can offer.  This
  2282. value can range anywhere from 0-Z (i.e., 0-35).  You should not mix
  2283. Checkbox and Radio buttons in the same group. -- unpredictable things
  2284. may happen if you do.
  2285.  
  2286. Some <flags> are mutually exclusive.  For example, you can only have
  2287. one of the "Plain", "Icon", or "Clipboard" flags chosen at once.  To
  2288. better assist you in determining which values can be combined with
  2289. each other, the right-most five columns in the next two tables
  2290. explain if the specific flag can be used under a specific condition.
  2291. For example, you cannot choose the "Hot Icon" flag if you are dealing
  2292. with a Clipboard Button.  Another example is that you cannot
  2293. underline the hotkey character in the label if it is not a Mouse
  2294. Button.
  2295.  
  2296. The following table contains the possible flag values for the <flags>
  2297. parameter.  Each of these values may be combined to achieve a
  2298. "composite" group of flags.  See the preceding paragraphs for a more
  2299. detailed explanation of this method.
  2300.  
  2301. Value Description of Flags Field #1   Icon Clip  Plain Mouse No-Mouse
  2302. ---------------------------------------------------------------------
  2303.     1 Button is a "Clipboard Button"   N     Y     N     Y     Y
  2304.     2 Button is "Invertable"           Y     Y     Y     Y     N
  2305.     4 Reset screen after button click  Y     Y     Y     Y     N
  2306.     8 Display Chisel special effect    Y     Y     Y     Y     Y
  2307.    16 Display Recessed special effect  Y     Y     Y     Y     Y
  2308.    32 Dropshadow the label (if any)    Y     Y     Y     Y     Y
  2309.    64 Auto-stamp image onto Clipboard  Y     Y     Y     Y     Y
  2310.   128 Button is an "Icon Button"       Y     N     N     Y     Y
  2311.   256 Button is a "Plain Button"       N     N     Y     Y     Y
  2312.   512 Display Bevel special effect     Y     Y     Y     Y     Y
  2313.  1024 Button is a Mouse Button         Y     Y     Y     Y     N
  2314.  2048 Underline hot-key in label       Y     Y     Y     Y     N
  2315.  4096 Make Icon Button use Hot Icons   Y     N     N     Y     N
  2316.  8192 Adj. vertical centering of label Y     Y     Y     Y     Y
  2317. 16384 Button belongs to a Radio Group  Y     Y     Y     Y     N
  2318. 32768 Display Sunken special effect    Y     Y     Y     Y     Y
  2319.  
  2320. The Icon Button, Clipboard button and Plain flags have already been   > v1.54
  2321. discussed.  Following, will be more discussion of the various flags   > v1.54
  2322. used in the preceding table:                                          > v1.54
  2323.                                                                       > v1.54
  2324.      BUTTON IS INVERTABLE (flag 2) - This means that the button       > v1.54
  2325.      will be inverted when clicked.  This flag is only useful         > v1.54
  2326.      when combined with the "Button is a Mouse Button - flag          > v1.54
  2327.      1024) flag.  Even if the button has special effects, those       > v1.54
  2328.      will be inverted as well as they are considered part of          > v1.54
  2329.      the button - all except for the Recessed effect.  The            > v1.54
  2330.      recessed effect is NEVER considered part of the actual           > v1.54
  2331.      button image, and will never be part of the mouse field,         > v1.54
  2332.      button's image or anything - it is just extra graphics.          > v1.54
  2333.                                                                       > v1.54
  2334.      RESET SCREEN AFTER BUTTON CLICK (flag 4) - This flag is          > v1.54
  2335.      used when the button is considered a Mouse Button (flag          > v1.54
  2336.      1024).  What this means is that when the user clicks on          > v1.54
  2337.      the button, the screen will be reset exactly the same            > v1.54
  2338.      as a RIP_RESET_WINDOWS command will do.  The reset is            > v1.54
  2339.      performed before the host command is processed (if any).         > v1.54
  2340.                                                                       > v1.54
  2341.      DISPLAY CHISEL SPECIAL EFFECT (flag 8) - This displays           > v1.54
  2342.      a special effect on-top of the button image that gives           > v1.54
  2343.      the visual impression of an indented gutter just to the          > v1.54
  2344.      inside of the button's border.  The amount of indentation        > v1.54
  2345.      varies depending on the size of the button.  See below           > v1.54
  2346.      for a table of indentation values for the Chisel effect.         > v1.54
  2347.                                                                       > v1.54
  2348.      DISPLAY RECESSED SPECIAL EFFECT (flag 16) - This places          > v1.54
  2349.      a recessed one-pixel bevel around the exterior of the            > v1.54
  2350.      button.  It is never considered part of the button's             > v1.54
  2351.      image.  Its purpose is to give the button a more 3D look         > v1.54
  2352.      by making it appear that the button is "poking through"          > v1.54
  2353.      a hole in a dialog box.  This effect is accomplished by          > v1.54
  2354.      placing a black outline (one pixel wide) around the              > v1.54
  2355.      exterior of the button's image (including bevel, etc),           > v1.54
  2356.      then placing a one-pixel wide inverted bevel around the          > v1.54
  2357.      black outline.                                                   > v1.54
  2358.                                                                       > v1.54
  2359.      DROPSHADOW THE LABEL IF ANY (flag 32) - This flag will           > v1.54
  2360.      instruct RIPscrip to place a dropshadowed version of the         > v1.54
  2361.      text label one pixel to the right and one pixel lower            > v1.54
  2362.      than the original label.  This is accomplished by drawing        > v1.54
  2363.      the label first in the <dback> color, then drawing the           > v1.54
  2364.      label offset up-left in the <dfore>.                             > v1.54
  2365.                                                                       > v1.54
  2366.      AUTO-STAMP IMAGE ONTO CLIPBOARD (flag 64) - This option          > v1.54
  2367.      is also known as "Auto-Clip".  What this means is right          > v1.54
  2368.      after the first button's image is rendered (including any        > v1.54
  2369.      special effects), it is automatically copied onto the            > v1.54
  2370.      clipboard.  The Recessed special effect is not considered        > v1.54
  2371.      part of the button image for this flag and is not made           > v1.54
  2372.      part of the clipboard image.  After the image is copied          > v1.54
  2373.      onto the clipboard, the label is drawn (this is so that          > v1.54
  2374.      the label is not placed onto the clipboard), then a              > v1.54
  2375.      number of flags in the current Button Style definition           > v1.54
  2376.      are altered.  Specifically, the Icon and Plain flags are         > v1.54
  2377.      disabled, and Clipboard button enabled (thus making any          > v1.54
  2378.      subsequent buttons use the resultant Clipboard button            > v1.54
  2379.      image for their button's representation).  In addition,          > v1.54
  2380.      the chisel, bevel, auto-clip and sunken flags are                > v1.54
  2381.      disabled.  The final result is a Clipboard button with           > v1.54
  2382.      no special effects other than the Recessed effect (if            > v1.54
  2383.      any).  This is most often used with Icon Buttons where           > v1.54
  2384.      every subsequent button uses the same Icon over and over         > v1.54
  2385.      again - the net result of this is less "disk thrashing"          > v1.54
  2386.      whenever a button is created; in addition, buttons will          > v1.54
  2387.      draw faster too.                                                 > v1.54
  2388.                                                                       > v1.54
  2389.      BUTTON IS AN ICON BUTTON (flag 128) - See previous               > v1.54
  2390.      discussions on button types above.                               > v1.54
  2391.                                                                       > v1.54
  2392.      BUTTON IS A PLAIN BUTTON (flag 256) - See previous               > v1.54
  2393.      discussions on button types above.                               > v1.54
  2394.                                                                       > v1.54
  2395.      DISPLAY BEVEL SPECIAL EFFECT (flag 512) - When this flag         > v1.54
  2396.      is active, a bevel will be drawn <size> pixels thick on          > v1.54
  2397.      the outside of the base image of the button.  This makes         > v1.54
  2398.      the button that many pixels wider and taller in each             > v1.54
  2399.      direction.  See the RIP_BUTTON for a more detailed               > v1.54
  2400.      description of the affects of the button's final size.           > v1.54
  2401.                                                                       > v1.54
  2402.      BUTTON IS A MOUSE BUTTON (flag 1024) - When this flag is         > v1.54
  2403.      enabled, the button becomes a clickable mouse region.            > v1.54
  2404.      When this option is in use, the Invert flag and several          > v1.54
  2405.      others are available (see the preceding chart).  When            > v1.54
  2406.      a button is a non-mouse button, then it is only used to          > v1.54
  2407.      draw a dialog box or an elaborate "static graphic" image         > v1.54
  2408.      of something that "looks" like a button.                         > v1.54
  2409.                                                                       > v1.54
  2410.      UNDERLINE HOT-KEYS IN LABEL (flag 2048) - When this              > v1.54
  2411.      flag is active, the first occurence of the hot-key               > v1.54
  2412.      character in the button's label will be underlined using         > v1.54
  2413.      the <uline_col> color.  Special care must be taken when          > v1.54
  2414.      underlining the character, taking into consideration if          > v1.54
  2415.      the character has a segment that goes below the "baseline"       > v1.54
  2416.      of the font.  Consult the following section to determine         > v1.54
  2417.      what ASCII characters have these "descenders".  Characters       > v1.54
  2418.      with descenders have the underline drawn slightly lower          > v1.54
  2419.      than for characters without them.                                > v1.54
  2420.                                                                       > v1.54
  2421.      MAKE ICON BUTTON USE HOT ICONS (flag 4096) - A Hot Icon          > v1.54
  2422.      is a button that has an alternative image when the button        > v1.54
  2423.      is "depressed".  Normally, when a button is an Icon              > v1.54
  2424.      button, some form of Icon File is used to create the image       > v1.54
  2425.      of the button (eg, EMAIL.ICN).  When the Hot Icon flag is        > v1.54
  2426.      in use, whenever that button is depressed, rather than           > v1.54
  2427.      using the normal Icon File for the button's image, a             > v1.54
  2428.      different Icon File is used for the button's image.  The         > v1.54
  2429.      filename would be the same filename as the original Icon,        > v1.54
  2430.      but with an extension of .HIC instead of .ICN.  When Hot         > v1.54
  2431.      Icon is in use, the alternative Icon is stamped in COPY          > v1.54
  2432.      mode.  If the file does not exist, then the original             > v1.54
  2433.      Icon's image is used, but pasted in NOT mode for the             > v1.54
  2434.      duration of the depression.                                      > v1.54
  2435.                                                                       > v1.54
  2436.      ADJ. VERTICAL CENTERING OF LABEL (flag 8192) - Some Labels       > v1.54
  2437.      may appear non-centered vertically when drawn using some         > v1.54
  2438.      fonts that are rather large.  With this in mind, you have        > v1.54
  2439.      the option to adjust the vertical centering.  What this          > v1.54
  2440.      does is take into consideration the height of any                > v1.54
  2441.      descenders of the label and calculate those into the             > v1.54
  2442.      overall height of the label before centering.  If this           > v1.54
  2443.      flag is not used, then the descenders are not taken into         > v1.54
  2444.      consideration when the vertical centering is calculated.         > v1.54
  2445.      See the Font Metric tables below for more detailed               > v1.54
  2446.      information on font sizes and their associated metrics.          > v1.54
  2447.      This command has no effect if the Label orientation is           > v1.54
  2448.      LEFT or RIGHT of the button.  It only applies to an              > v1.54
  2449.      orientation of TOP, BOTTOM or CENTER.                            > v1.54
  2450.                                                                       > v1.54
  2451.      BUTTON BELONGS TO A RADIO GROUP (flag 16384) - When this         > v1.54
  2452.      flag is used, then any buttons defined in this button            > v1.54
  2453.      <group_no> are considered to be radio buttons where only         > v1.54
  2454.      one of the buttons can be clicked (selected) at any              > v1.54
  2455.      particular time.  If a button is not a radio button or           > v1.54
  2456.      a checkbox button, then the "selected" flag of the               > v1.54
  2457.      RIP_BUTTON command is ignored.  When a Radio Button is           > v1.54
  2458.      clicked, any other radio button in that button group that        > v1.54
  2459.      is selected is automatically de-selected and the current         > v1.54
  2460.      one selected.  Any host command is processed at the time         > v1.54
  2461.      of the button click.  If a Radio Button is drawn initally        > v1.54
  2462.      as selected, then that host command is processed at the          > v1.54
  2463.      time of its initial drawing.  See the section near the           > v1.54
  2464.      end of this document discussing TEMPLATES for a more             > v1.54
  2465.      complete description of Radio Buttons and how they               > v1.54
  2466.      interact with their Button Group and with each other.            > v1.54
  2467.                                                                       > v1.54
  2468.      DISPLAY SUNKEN SPECIAL EFFECT (flag 32768) - When this           > v1.54
  2469.      option is enabled, a one-pixel inverted bevel is drawn           > v1.54
  2470.      exactly one pixel to the inside of the base image of the         > v1.54
  2471.      button.  This and the chisel effect are the only two             > v1.54
  2472.      special effects which physically "overwrite" portions of         > v1.54
  2473.      the base button image.                                           > v1.54
  2474.  
  2475. This array defines which characters have descenders (portions of
  2476. their font that go below the baseline).  This information is used in
  2477. the vertical centering of button text labels.
  2478.  
  2479. char low_char[256] =
  2480. {
  2481.     0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
  2482.     0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
  2483.     0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
  2484.     0,0,0,0,0,0,0,1,0,0,1,0,0,0,0,0,1,1,0,0,0,0,0,0,0,1,0,0,0,0,0,0,
  2485.     1,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,1,
  2486.     0,0,0,0,0,0,0,0,0,0,0,1,1,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
  2487.     1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
  2488.     0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0
  2489. };
  2490.  
  2491. struct METRIC
  2492. {
  2493.     unsigned char top;    // Scan lines from TOP OF CELL to char top
  2494.     unsigned char bow;    // Scan lines from TOC to crest of char
  2495.     unsigned char base;   // Scan lines from TOC to baseline
  2496.     unsigned char drop;   // Scan lines from TOC to lowermost pixel
  2497. };
  2498.  
  2499. The METRIC structure can be described visually as follows:
  2500.  
  2501.                       0 --+----------+----------+
  2502.                           |          |          |
  2503.                      TOP__|__________|__________|
  2504.                           | #        |          |
  2505.                           | #        |          |
  2506.                           | #        |          |
  2507.                      BOW__|_#________|___   _ __|
  2508.                           | # ###    |   ### #  |
  2509.                           | ##   #   |  #   ##  |
  2510.                           | #     #  | #     #  |
  2511.                           | #     #  | #     #  |
  2512.                           | #     #  | #     #  |
  2513.                           | #     #  |  #   ##  |
  2514.                     BASE__|_#_____#__|___###_#__|
  2515.                           |          |       #  |
  2516.                           |          |       #  |
  2517.                           |          |       #  |
  2518.                           |          |  #   #   |
  2519.                     DROP__|__________|___###____|
  2520.                           |          |          |
  2521.                     END --+----------+----------+
  2522.  
  2523. Notice that the topmost scan line of a font cell is not necessarily
  2524. the top of the character.  The top field of the structure contains
  2525. the vertical offset from the top of the cell for all fonts in that
  2526. set.
  2527.  
  2528.  
  2529.     Default Font (Font 0)               Triplex Font (Font 1)
  2530.  
  2531. Size  Top    Bow   Base   Drop     Size   Top   Bow     Base   Drop
  2532. ------------------------------     --------------------------------
  2533.   1    0      2      6      7        1     6     10      18     22
  2534.   2    0      4     13     15        2     6     11      20     24
  2535.   3    0      6     20     23        3     8     13      23     28
  2536.   4    0      8     27     31        4     10    17      31     38
  2537.   5    0     10     34     39        5     13    23      41     50
  2538.   6    0     12     41     47        6     16    28      51     62
  2539.   7    0     14     48     55        7     20    34      62     76
  2540.   8    0     16     55     63        8     25    42      77     94
  2541.   9    0     18     62     71        9     30    51      93    114
  2542.  10    0     20     69     79       10     40    67     124    152
  2543.  
  2544.  
  2545.     Small Font (Font 2)                 Sans Serif Font (Font 3)
  2546.  
  2547. Size  Top    Bow   Base   Drop     Size   Top   Bow     Base   Drop
  2548. ------------------------------     --------------------------------
  2549.   1    2      3      5      6        1      7    11      19     23
  2550.   2    2      4      6      7        2      7    12      21     25
  2551.   3    2      3      6      7        3      9    14      24     29
  2552.   4    3      5      9     11        4     11    18      32     39
  2553.   5    4      7     12     14        5     14    24      42     51
  2554.   6    5      9     15     18        6     18    30      53     64
  2555.   7    6     10     13     22        7     22    36      64     78
  2556.   8    7     12     22     27        8     28    45      80     97
  2557.   9    9     15     27     33        9     33    54      96    117
  2558.  10   12     20     36     44       10     74   102     158    186
  2559.  
  2560.  
  2561.  
  2562.      Gothic Font (Font 4)                Script Font (Font 5)
  2563.  
  2564. Size  Top    Bow   Base   Drop     Size   Top   Bow     Base   Drop
  2565. ------------------------------     --------------------------------
  2566.   1    7     11     19     23        1     10    17      22     29
  2567.   2    7     12     21     25        2     10    18      24     32
  2568.   3    9     14     24     29        3     12    21      27     36
  2569.   4   11     18     32     39        4     16    28      37     49
  2570.   5   14     24     42     51        5     21    37      49     65
  2571.   6   18     30     53     64        6     26    46      61     80
  2572.   7   22     36     64     78        7     32    56      74     98
  2573.   8   28     45     80     97        8     40    70      92    122
  2574.   9   33     54     96    117        9     48    84     111    147
  2575.  10   44     72    128    156       10     63   111     147    195
  2576.  
  2577.  
  2578.  
  2579.     Simplex Font (Font 6)            Triplex Script Font (Font 7)
  2580.  
  2581. Size  Top    Bow   Base   Drop     Size   Top   Bow     Base   Drop
  2582. ------------------------------     --------------------------------
  2583.   1    9     13     21     25        1      5     9      17     21
  2584.   2    9     14     23     27        2      5    10      19     23
  2585.   3   11     16     26     31        3      7    12      22     27
  2586.   4   14     21     35     42        4      9    16      30     37
  2587.   5   18     28     46     56        5     12    22      40     49
  2588.   6   23     35     58     69        6     15    27      50     61
  2589.   7   28     42     70     84        7     19    33      61     75
  2590.   8   35     52     87    104        8     24    41      77     93
  2591.   9   42     63    105    126        9     29    50      92    113
  2592.  10   56     84    140    168       10     39    67     123    151
  2593.  
  2594.  
  2595.  
  2596.     Complex Font (Font 8)               European Font (Font 9)
  2597.  
  2598. Size  Top    Bow   Base   Drop     Size   Top   Bow     Base   Drop
  2599. ------------------------------     --------------------------------
  2600.   1    8     12     20     24        1      7    14      32     38
  2601.   2    8     13     22     26        2      7    15      35     41
  2602.   3   10     15     25     30        3      9    18      40     47
  2603.   4   13     20     34     41        4     12    24      54     64
  2604.   5   17     27     45     54        5     16    32      72     85
  2605.   6   22     34     57     68        6     20    40      96    106
  2606.   7   27     41     69     83        7     25    49     109    129
  2607.   8   34     51     86    103        8     31    61     136    161
  2608.   9   41     62    104    125        9     38    74     164    194
  2609.  10   54     83    139    167       10     51    99     219    259
  2610.  
  2611.  
  2612.  
  2613.      Bold Font (Font 10)
  2614.  
  2615. Size  Top    Bow   Base   Drop
  2616. ------------------------------
  2617.   1   11     17     35     39
  2618.   2   13     19     39     43
  2619.   3   14     22     44     49
  2620.   4   19     29     59     66
  2621.   5   27     39     79     88
  2622.   6   33     49     99    110
  2623.   7   39     59    119    133
  2624.   8   49     74    149    166
  2625.   9   59     89    179    200
  2626.  10   79    199    239    267
  2627.  
  2628. The Chisel effect draws a dropshadowed line around the inside of the
  2629. button.  How far from the borders of the button are determined by
  2630. this table:
  2631.  
  2632.         Height of Button     X inset     Y inset
  2633.         ----------------------------------------
  2634.             0 - 11              1          1
  2635.            12 - 24              3          2
  2636.            25 - 39              4          3
  2637.            40 - 74              6          5
  2638.            75 - 149             7          5
  2639.           150 - 199             8          6
  2640.           200 - 249            10          7
  2641.           250 - 299            11          8
  2642.           300 -                13          9
  2643.  
  2644. This table describes the possible flag settings for the <flags2>
  2645. parameter:
  2646.  
  2647. Val Description of Flags Field #2    Icon Clip Plain Mouse No-Mouse
  2648. -------------------------------------------------------------------
  2649.  1  Button is in a check box group     Y    Y    Y     Y       N
  2650.  2  Highlight hotkey character         Y    Y    Y     Y       N
  2651.  4  Explode (zoom out when clicked)    Y    Y    Y     Y       N
  2652.  8  Left Justify Label (top/ctr/btm)   Y    Y    Y     Y       Y
  2653. 16  Right Justify Label (top/ctr/btm)  Y    Y    Y     Y       Y
  2654.  
  2655. Following is a more complete description of the flags described in    > v1.54
  2656. the <flags2> parameter:                                               > v1.54
  2657.                                                                       > v1.54
  2658.      BUTTON IS IN A CHECK BOX GROUP (flag 1) - When this flag is      > v1.54
  2659.      selected, then the button <group_no> is considered a Check-      > v1.54
  2660.      box group.  When in this mode, the Radio Group flag is not       > v1.54
  2661.      accessible - A Button Group can be a Radio Button, a Check-      > v1.54
  2662.      box button or neither, but not more than one at the same         > v1.54
  2663.      time.  A Check-box button group is a group of buttons where      > v1.54
  2664.      each button in the group can be either ON or OFF in any          > v1.54
  2665.      combination.  In this way, more than one button in the           > v1.54
  2666.      group can be clicked at the same time.  See the TEMPLATES        > v1.54
  2667.      section later on in this document for a complete discussion      > v1.54
  2668.      of how the Host Commands are processed for Check-Box buttons.    > v1.54
  2669.      If a check-box button is drawn as "pre-selected", then the       > v1.54
  2670.      Host Command is processed immediately upon inital drawing of     > v1.54
  2671.      the button (when it is received).                                > v1.54
  2672.                                                                       > v1.54
  2673.      HIGHLIGHT HOTKEY CHARACTER (flag 2) - When this flag is          > v1.54
  2674.      active, then the first occurence of the hotkey character         > v1.54
  2675.      in the label will be hilighted using the <uline_col> color.      > v1.54
  2676.      This gives the user a visual impression of what keystroke        > v1.54
  2677.      they need to type in order to activate the button without        > v1.54
  2678.      the mouse.                                                       > v1.54
  2679.                                                                       > v1.54
  2680.      EXPLODE (ZOOM OUT WHEN CLICKED) (flag 4) - This optional         > v1.54
  2681.      flag is designed to "zoom out" from the button when the          > v1.54
  2682.      user clicks on it.  What is generally done is a dotted           > v1.54
  2683.      rectangle is drawn initially around the button and it is         > v1.54
  2684.      repeatedly redrawn over itself in XOR mode, constantly           > v1.54
  2685.      getting larger and larger until it hits the full size of         > v1.54
  2686.      the screen.  This gives the visual impression that the           > v1.54
  2687.      button is zooming out to another screen.  Each time another      > v1.54
  2688.      frame of the zooming rectangle is drawn, the previous            > v1.54
  2689.      rectangle on the inside of the new one is erased by XOR          > v1.54
  2690.      drawing the same rectangle over itself again.  This option       > v1.54
  2691.      does not need to be supported in order to be considered          > v1.54
  2692.      a RIPscrip terminal, although it would be nice.  In              > v1.54
  2693.      other words, this is not a "make or break" feature.              > v1.54
  2694.                                                                       > v1.54
  2695.      LEFT JUSTIFY LABEL (TOP/CTR/BTM) (flag 8) - If this option       > v1.54
  2696.      is enabled, then any TOP, CENTER or BOTTOM label orientations    > v1.54
  2697.      will be left justified to the left edge of the button.  The      > v1.54
  2698.      exact indentation of the label from the interior of the          > v1.54
  2699.      button's base image depends on whether the chisel effect         > v1.54
  2700.      is active.  If chisel is OFF, then the indentation is 10         > v1.54
  2701.      pixel.  If chisel is ON, then the indentation is 20 pixels.      > v1.54
  2702.      This option can be combined with the Adjust Vertical Centering   > v1.54
  2703.      flag only if the label orientation is CENTER.                    > v1.54
  2704.                                                                       > v1.54
  2705.      RIGHT JUSTIFY LABEL (TOP/CTR/BTM) (flag 16) - If this option     > v1.54
  2706.      is enabled, then any TOP, CENTER or BOTTOM label orientations    > v1.54
  2707.      will be right justified to the right edge of the button.  The    > v1.54
  2708.      exact indentation of the label from the interior of the          > v1.54
  2709.      button's base image depends on whether the chisel effect         > v1.54
  2710.      is active.  If chisel is OFF, then the indentation is 10         > v1.54
  2711.      pixel.  If chisel is ON, then the indentation is 20 pixels.      > v1.54
  2712.      This option can be combined with the Adjust Vertical Centering   > v1.54
  2713.      flag only if the label orientation is CENTER.                    > v1.54
  2714.  
  2715.  
  2716.  
  2717. ---------------------------------------------------------------------
  2718. RIP_BUTTON
  2719. ---------------------------------------------------------------------
  2720.          Function:  Define a Mouse Button
  2721.             Level:  1
  2722.           Command:  U
  2723.         Arguments:  x0:2 y0:2 x1:2 y1:2 hotkey:2 flags:1 res:1
  2724.                     ...text
  2725.            Format:  !|1U <x0> <y0> <x1> <y1> <hotkey> <flags>
  2726.                     <res> <text>
  2727.           Example:  !|1U010100003200iconfile<>Label<>HostCmd^m
  2728.   Uses Draw Color:  NO
  2729. Uses Line Pattern:  NO
  2730.   Uses Line Thick:  NO
  2731.   Uses Fill Color:  NO
  2732. Uses Fill Pattern:  NO
  2733.   Uses Write Mode:  NO
  2734.   Uses Font Sizes:  YES
  2735.     Uses Viewport:  YES                                               > v1.54
  2736.  
  2737. This command physically creates a new Button using the previously
  2738. described RIP_BUTTON_STYLE command.  You may have at most 128
  2739. different Mouse Buttons (you may have any number of non-Mouse
  2740. Buttons).
  2741.  
  2742. The <x0> and <y0> parameters for this command designate the
  2743. upper-left corner of the Button.  This (X,Y) location may not be the
  2744. actual "absolute" corner position of the Button, as it may be
  2745. adjusted via the Special Effects functions that are part of the
  2746. RIP_BUTTON_STYLE command (see above).
  2747.  
  2748. The <x1> and <y1> parameters are only used for Plain Buttons when you
  2749. have not specified a specific Height and Width in the
  2750. RIP_BUTTON_STYLE command.  These parameters are used in Dynamically
  2751. Sized Buttons.  If the Height and Width in the RIP_BUTTON_STYLE are
  2752. non-zero, then these two parameters are set to zero.
  2753.  
  2754. The (x0,y0) and (x1,y1) parameters will be modified by the following
  2755. values for the different special effects:
  2756.  
  2757.   Effect Type   X0 Modifier   Y0 Modifier   X1 Modifier   Y1 Modifier
  2758.   -------------------------------------------------------------------
  2759.   Bevel         -bevel size   -bevel size   +bevel size   +bevel size
  2760.   Recess            -2            -2            +2            +2
  2761.   Sunken            0             0             0             0
  2762.   Chisel            0             0             0             0
  2763.  
  2764. The <hotkey> parameter is only used with Mouse Buttons.  It is the
  2765. ASCII code for the keystroke that will activate this Button.  It is
  2766. represented as a two-digit MegaNum.  If this character exists in the
  2767. text label, and the Underline flag or hilight hotkey flag is enabled  > v1.54
  2768. in the RIP_BUTTON_STYLE, then the character will be underlined in the
  2769. label.  Control codes are allowable, and a value of 255 (decimal)
  2770. corresponds to "any" key.
  2771.  
  2772. The <flags> parameter provides several different functions for each
  2773. button.  The possible "combinatorial" flags for this parameter are
  2774. listed in the following table.  Note that these values may be
  2775. combined together (by adding their values) to arrive at the final
  2776. flag parameter's value.
  2777.     
  2778.         Value  Description
  2779.         --------------------------------------------------
  2780.           1    Draw button as already selected
  2781.           2    Button is "default" when <ENTER> is pressed
  2782.  
  2783. Using a flag of 1 means that the Button is already "selected".  By
  2784. selected, we mean that it is already clicked and should be initially
  2785. drawn as clicked.  This is typically used for Radio Buttons and/or
  2786. Check Boxes.  This only affects the image.  The Host Command WILL NOT
  2787. be automatically sent to the host when a selected Button is drawn. If
  2788. this parameter is set to 0, then the Button will be drawn in normal,
  2789. unselected mode.
  2790.  
  2791. The <text> parameter for this command is somewhat different than
  2792. those found in previously described RIPscrip commands.  All other
  2793. RIPscrip commands only have one text parameter.  This command
  2794. requires  anywhere from 0-3 text parameters.  The way RIPscrip
  2795. accomplishes this is by separating each block in the <text> parameter
  2796. with the delimiter "<>".  This text parameter delimiter is not needed
  2797. before the first text block, but is necessary between the 1st and 2nd
  2798. blocks, and the 2nd and 3rd blocks.  Here is an example of a typical
  2799. text parameter for this command:
  2800.  
  2801.      ICONFILE.ICN<>TEXT LABEL<>HOST COMMAND
  2802.  
  2803. The actual syntax of this text parameter is as follows:
  2804.  
  2805.      [icon-file][[<>text-label][<>host-command]]
  2806.  
  2807. The block described as ICONFILE.ICN is actually the Icon Filename
  2808. that will be used for the Button if it is an Icon Button.  If it is
  2809. not an Icon Button, then this block will read "<>" all by itself (a
  2810. "null" block).
  2811.  
  2812. The .ICN file extension does not need to be included as part of the
  2813. filename.  If omitted, it will automatically be appended to the
  2814. filename.  If an extension is provided, it will be used verbatim.
  2815.  
  2816. The "TEXT LABEL" block is actually the text that will be used to
  2817. descriptively label the Button.  You may also specify a "null" block
  2818. for no label (i.e., "<>").
  2819.  
  2820. The final block of the <text> parameter is the Host Command.  This
  2821. block contains any text that should be sent to the Host after this
  2822. Button is clicked.  This may contain any Control Characters,
  2823. Pick-List definitions, Text Variables or Template Definitions.  This
  2824. block might be "segmented" into multiple Host Command segments.  See
  2825. the section entitled HOST COMMANDS in this Manual for additional
  2826. information on these Host Command features.
  2827.  
  2828. When this command is stored in-memory, it is converted to global      > v1.54
  2829. screen coordinates (for internal storage only).  This makes it so     > v1.54
  2830. that if you have mouse button regions defined in multiple different   > v1.54
  2831. viewports, that each field will be properly inverted at the right     > v1.54
  2832. location regardless of the currently defined viewport.                > v1.54
  2833.  
  2834. NOTE: All Mouse Fields are scanned in "last in, first out" order.     > v1.54
  2835.       This means that the last-most received Mouse Button will be     > v1.54
  2836.       the first one scanned for a mouse click.                        > v1.54
  2837.  
  2838.  
  2839. Not all of the blocks in the <text> parameter need to be specified.
  2840. Here are examples of the valid combinations of text blocks:
  2841.  
  2842.   Parameter Example       Description of the Text Parameter
  2843.   -------------------------------------------------------------------
  2844.   icon<>label<>host_cmd   Specify all three blocks
  2845.     <>label<>host_cmd     2 blocks specified; no icon
  2846.       icon<>label<>       2 blocks specified; no host  command
  2847.        icon<>label        2 blocks specified; no host  command
  2848.       <><>host_cmd        1 block  specified; no icon  or label
  2849.        <>label<>          1 block  specified; no icon  or host command
  2850.         <>label           1 block  specified; no icon  or host command
  2851.        icon<><>           1 block  specified; no label or host command
  2852.         icon<>            1 block  specified; no label or host command
  2853.          icon             1 block  specified; no label or host command
  2854.         <><><>            A blank text parameter; all blocks omitted
  2855.          <><>             A blank text parameter; all blocks omitted
  2856.           <>              A blank text parameter; all blocks omitted
  2857.  
  2858. NOTE:  The <res> parameter is reserved for future use by TeleGrafix
  2859.        Communications, Inc..  It should be set to 0 for compatibility
  2860.        with future releases.
  2861.  
  2862.  
  2863.  
  2864. ---------------------------------------------------------------------
  2865. RIP_DEFINE
  2866. ---------------------------------------------------------------------
  2867.          Function:  Define a text variable
  2868.             Level:  1
  2869.           Command:  D
  2870.         Arguments:  flags:3 res:2 ...text
  2871.            Format:  !|1D <flags> <res> <text>
  2872.           Example:  !|1D00700text_var,60:?question?default data
  2873.   Uses Draw Color:  NO
  2874. Uses Line Pattern:  NO
  2875.   Uses Line Thick:  NO
  2876.   Uses Fill Color:  NO
  2877. Uses Fill Pattern:  NO
  2878.   Uses Write Mode:  NO
  2879.   Uses Font Sizes:  NO
  2880.     Uses Viewport:  NO                                                > v1.54
  2881.  
  2882. This command is used to create a text variable on the Client system
  2883. (i.e., the Terminal system).  A text variable is more fully covered
  2884. in the HOST COMMANDS section.  Simply put, a text variable is a piece
  2885. of information assigned to a 1-12 character identifier that can
  2886. either be saved to a local database file (static variables), or to
  2887. memory (dynamic variables).  Variable Identifiers can be 1-12
  2888. characters in length.  You may use any alphanumeric character and
  2889. underscores (_) in the identifier.  An underscore cannot be the first
  2890. character, nor can the first character of an identifier be a number.
  2891.  
  2892. The <flags> parameter of this command combines three separate values
  2893. into one MegaNum flag that determines how the variable definition
  2894. will operate.  Here are the possible flag values:
  2895.  
  2896.         Value     Description of Flag
  2897.         ---------------------------------------
  2898.         001     Save Variable to database
  2899.         002     Cannot specify a blank response
  2900.         004     Non-interactive query
  2901.  
  2902. When a variable is flagged as "Save to Database", it becomes a part
  2903. of the Client system's actual configuration.  The value is saved
  2904. indefinitely until either changed, or manually erased.  You may
  2905. choose not to allow the user to enter a blank response.  This
  2906. basically requires them to enter some piece of information for the
  2907. variable.
  2908.  
  2909. The last flag determines whether the definition is interactive or not.
  2910. An interactive definition will attempt to define the variable.  If it
  2911. does exist, it pops the value up on the screen asking the user to
  2912. confirm if the value is correct.  If it does not exist, a similar
  2913. pop-up box will appear asking the user to enter some data for the
  2914. given variable.
  2915.  
  2916. In a non-interactive situation, the Client system will check to see
  2917. if the variable exists.  If it does, then nothing happens (unless a
  2918. default response is specified in this command, whereby the Client's
  2919. variable is updated with the new information).  If the value is not
  2920. defined, then this definition becomes interactive by default, since
  2921. the user actually has to enter something anyway.
  2922.  
  2923. The <text> parameter for this command is also segmented in nature,
  2924. much like the RIP_BUTTON command is.  An example of a segmented
  2925. <text> parameter for the RIP_DEFINE command might be as follows:
  2926.  
  2927.           FULL_NAME,30:?What is your full name?John Doe
  2928.  
  2929. The actual syntax of the Variable Define text parameter is as
  2930. follows:
  2931.  
  2932.   variable-identifier[,field-width]:[?question-text?][default-value]
  2933.  
  2934. There are several different segments in this parameter as you can
  2935. see.  The first section is the variable- identifier.  Immediately
  2936. after it is an optional field-width.  If the field width is omitted,
  2937. it will default to a value of  60.  You should limit the values of
  2938. this width from 1-60.
  2939.  
  2940. Immediately following the identifier field-width parameter is a colon
  2941. (:).  The colon indicates that the variable identifier field is
  2942. completed and that the remainder of the text parameter is to contain
  2943. the question and/or the default response (if any).  If no question or
  2944. default response is provided, the text parameter would read
  2945. "TEXT_VAR,width:" with no additional data.
  2946.  
  2947. The question-text is specified by a question mark (?) followed by the
  2948. actual text of the question, followed by a trailing question mark.
  2949. The basic format of the question segment is as follows:
  2950.  
  2951.                     ?this is a question?
  2952.  
  2953. The remainder of the text parameter consists of a default-value for
  2954. the variable's contents.  It may be omitted if you wish, to make it
  2955. so that the user must enter his/her own value instead of some "canned
  2956. response".
  2957.  
  2958. NOTE:  The <res> parameter is reserved for future use by TeleGrafix
  2959.        Communications, Inc..  It should be set to 00 for
  2960.        compatibility with future releases.
  2961.  
  2962.  
  2963.  
  2964. ---------------------------------------------------------------------
  2965. RIP_QUERY
  2966. ---------------------------------------------------------------------
  2967.          Function:  Query the contents of a text variable
  2968.             Level:  1
  2969.           Command:  <escape>
  2970.         Arguments:  mode:1 res:3 ...text
  2971.            Format:  !|1<escape> <mode> <res> <text>
  2972.           Example:  !|1<escape>0000this is a query $COMMAND$^m
  2973.   Uses Draw Color:  NO
  2974. Uses Line Pattern:  NO
  2975.   Uses Line Thick:  NO
  2976.   Uses Fill Color:  NO
  2977. Uses Fill Pattern:  NO
  2978.   Uses Write Mode:  NO
  2979.   Uses Font Sizes:  NO
  2980.     Uses Viewport:  NO                                                > v1.54
  2981.  
  2982. NOTE:  <escape> is used to indicate the Escape character (ASCII 27
  2983.        or ESC).
  2984.  
  2985. The Query Text Variable RIPscrip command instructs the terminal to
  2986. immediately respond with some piece of information, whether
  2987. statically stored (i.e., in a database), stored internally in RAM
  2988. (dynamic information), or pre-defined Text Variables.
  2989.  
  2990. This command is unique in RIPscrip in the fact that the command
  2991. character that is used is NOT a printable character.  We use the
  2992. escape character (ASCII 27) to introduce this command as a measure of
  2993. security.  Since the query command can query the terminal for some
  2994. critical (potentially private) information, you would not want a user
  2995. to be able to query another user's terminal for something like his
  2996. address information, or something that he wouldn't want to otherwise
  2997. divulge to unauthorized people.  Since most hosts do not allow the
  2998. user to enter an escape character, this character is ideal for this
  2999. purpose.  Using escape allows only the Host (under most
  3000. circumstances) to be in control of any queries.
  3001.  
  3002. NOTE:  This command is very flexible in that you can specify
  3003.        control characters, pick-list definitions, Text Variables,
  3004.        and Host Command template definitions.  See the section
  3005.        entitled HOST COMMANDS for a more detailed explanation
  3006.        of these features.
  3007.  
  3008. Whether the information is transmitted instantly or not is dependent
  3009. on the <mode> parameter.  The <mode> parameter determines when data
  3010. queries are processed.  The possible settings for the <mode>
  3011. parameter are as follows:
  3012.  
  3013.  
  3014.     Mode     Description
  3015.     ----------------------------------------------------------------
  3016.      0    Process the query command NOW (upon receipt)
  3017.      1    Process when mouse clicked in Graphics Window
  3018.      2    Process when mouse clicked in Text Window (any text
  3019.           variables that return X or Y mouse coordinates return TEXT
  3020.           coordinates, not graphics coordinates in this mode.  These
  3021.           coordinates are two-digit values instead of the graphical
  3022.           values that are four digits).
  3023.  
  3024. Note that modes 1-2 do not return the results of the Query instantly.
  3025. They query commands are processed when the user clicks the mouse
  3026. either in the text window, or in the graphics window respectively.
  3027. These "queries after mouse clicks" are only acted upon if the user is
  3028. clicking on something other than a Button or a Mouse Field. To
  3029. disable these two special "deferred" query modes, issue the same
  3030. command with the query string of $OFF$.  This will disable this
  3031. mode.  Providing a <text> parameter of anything other than $OFF$ will
  3032. produce a revised query command (active).
  3033.  
  3034. Basically put, a Query command will be immediately acted upon by the
  3035. Terminal program when received.  The Query command's <text> parameter
  3036. can contain any number of Host Command "segments", which can instruct
  3037. the terminal "how to" send data to the host, and more specifically,
  3038. what data to send to the host.
  3039.  
  3040. Some examples of query statements might be any of the following:
  3041.  
  3042.                         ^m     Send a carriage return to the BBS now!
  3043.   My name is $FULL_NAME$^m     Send text "My name is <insert-name-
  3044.                                here>" followed by a  carriage return
  3045.                                to the BBS.  The <insert-name-here>
  3046.                                will be replaced with whatever the
  3047.                                variable $FULL_NAME$ contains.
  3048.  
  3049. See the section entitled HOST COMMANDS for a detailed explanation of
  3050. Host Commands, and what you can do with the Query command.
  3051.  
  3052. NOTE:  The <res> parameter is reserved for future use by TeleGrafix
  3053.        Communications, Inc..  It should be set to 000 for
  3054.        compatibility with future releases.
  3055.  
  3056.  
  3057.  
  3058. ---------------------------------------------------------------------
  3059. RIP_COPY_REGION
  3060. ---------------------------------------------------------------------
  3061.          Function:  Copy screen region up/down
  3062.             Level:  1
  3063.           Command:  G
  3064.         Arguments:  x0:2 y0:2 x1:2 y1:2 res:2 dest_line:2
  3065.            Format:  !|1G <x0> <y0> <x1> <y1> <res> <dest_line>
  3066.           Example:  !|1G080G140M0005
  3067.   Uses Draw Color:  NO
  3068. Uses Line Pattern:  NO
  3069.   Uses Line Thick:  NO
  3070.   Uses Fill Color:  NO
  3071. Uses Fill Pattern:  NO
  3072.   Uses Write Mode:  NO
  3073.   Uses Font Sizes:  NO
  3074.     Uses Viewport:  NO                                                > v1.54
  3075.  
  3076. This command physically "copies" a rectangular region of the graphics
  3077. screen up or down.  The <dest_line> parameter is the Y position that
  3078. is the destination scan line to receive the region.  The Destination
  3079. of the copy can overlap the original region, but cannot be on the
  3080. same line.  You cannot move the image area left or right at all.  This
  3081. command is designated for vertical scrolling of graphical data either
  3082. up or down.
  3083.  
  3084. Due to hardware restrictions, the X0 and X1 parameters must be evenly
  3085. divisible by eight (8) (e.g., 0, 8, 16, etc.).  If the X0 and X1
  3086. parameters are NOT evenly divisible by eight, then the X0 parameter
  3087. will be reduced to the next most eight-pixel boundary, and the X1
  3088. parameter will be increased to the next eight-pixel boundary.  For
  3089. example, if X0=14, and X1=38, then X0 would be adjusted DOWN to 8,
  3090. and X1 would be adjusted UP to 40.  This is to ensure that the
  3091. desired graphical region is scrolled.
  3092.  
  3093. The original image area is left on the screen (is not cleared).  So if
  3094. you wish to perform some kind of scrolling effect, you will have to
  3095. clear the original area yourself.
  3096.  
  3097. If the destination region would place the image partially off-screen,
  3098. then the entire command is ignored!
  3099.  
  3100. This is one of the only graphical output commands that DOES NOT       > v1.54
  3101. adhere to the RIP_VIEWPORT command.  In other words, you can scroll   > v1.54
  3102. graphical data outside the current graphical viewport (even over the  > v1.54
  3103. text window!).                                                        > v1.54
  3104.  
  3105. NOTE:  The <res> parameter is reserved for future development by
  3106.        TeleGrafix.
  3107.  
  3108.  
  3109.  
  3110. ---------------------------------------------------------------------
  3111. RIP_READ_SCENE
  3112. ---------------------------------------------------------------------
  3113.          Function:  Playback local .RIP file
  3114.             Level:  1
  3115.           Command:  R
  3116.         Arguments:  res:8 filename...
  3117.            Format:  !|1R <res> <filename>
  3118.           Example:  !|1R00000000testfile.rip
  3119.   Uses Draw Color:  YES
  3120. Uses Line Pattern:  YES
  3121.   Uses Line Thick:  YES
  3122.   Uses Fill Color:  YES
  3123. Uses Fill Pattern:  YES
  3124.   Uses Write Mode:  YES
  3125.   Uses Font Sizes:  YES
  3126.     Uses Viewport:  NO                                                > v1.54
  3127.  
  3128. This command instructs the remote terminal to playback a local .RIP
  3129. file.  The current execution of RIPscrip commands will be temporarily
  3130. suspended and the contents of the designated RIP file will begin
  3131. executing.  Regardless of whether or not the current RIPscrip code
  3132. coming across the modem is in the middle of a line or not, the RIP
  3133. playback file will be assumed to start at the beginning of a line.
  3134. Therefore, if a RIP_READ_SCENE command is located in a .RIP file, it
  3135. must be the very last command on the line, followed by a carriage
  3136. return instead of a command delimiter (|).  This ensures that the
  3137. loaded .RIP file will begin executing properly with the correct
  3138. delimiters found in the correct places.
  3139.  
  3140. The RIP playback file can alter colors, fonts, or whatever.  Once the
  3141. playback of the file is complete, the remaining RIPscrip code that
  3142. was temporarily suspended will be resume execution.  Any changes that
  3143. appeared in the loaded playback file will remain in effect when the
  3144. resumed code is processed.  In other words, if you change a color or
  3145. a font in the playback file and leave them changed, they will remain
  3146. in effect during the resumed execution.
  3147.  
  3148. NOTE:  The <res> parameter is reserved for future development by
  3149.        TeleGrafix.  It should be set to "00000000" for compatibility
  3150.        with future releases.
  3151.  
  3152.  
  3153.  
  3154. ---------------------------------------------------------------------
  3155. RIP_FILE_QUERY
  3156. ---------------------------------------------------------------------
  3157.          Function:  Query existing information on a particular file
  3158.             Level:  1
  3159.           Command:  F
  3160.         Arguments:  mode:2 res:4 filename...
  3161.            Format:  !|1F <mode> <res> <filename>
  3162.           Example:  !|1F010000testfile.icn
  3163.   Uses Draw Color:  NO
  3164. Uses Line Pattern:  NO
  3165.   Uses Line Thick:  NO
  3166.   Uses Fill Color:  NO
  3167. Uses Fill Pattern:  NO
  3168.   Uses Write Mode:  NO
  3169.   Uses Font Sizes:  NO
  3170.     Uses Viewport:  NO                                                > v1.54
  3171.  
  3172. This command queries the existence of a particular file, regardless
  3173. of type.  It is intended for host systems to determine if a
  3174. particular Icon or RIP file exists on the terminal;s hard disk.
  3175.  
  3176. There are a variety of ways you can query for filenames.  The <mode>
  3177. parameter determines the command's response.  This command instructs
  3178. the terminal to send a response to the host immediately upon
  3179. execution.
  3180.  
  3181. The following table is a listing of the possible values for <mode>:
  3182.  
  3183. Mode  Description
  3184. ----------------------------------------------------------------------
  3185.  00   Simply query the existence of the file.  If it exists, a "1" is
  3186.       returned.  Otherwise a "0" is returned to the Host (without a
  3187.       carriage return).
  3188.  01   Same as 0, except a carriage return is added after the response.
  3189.  02   Queries the existence of a file.  If it does not exist, a "0" is
  3190.       returned to the Host followed by a carriage return.  If it does
  3191.       exist, the returned text is a "1." followed by the file size (in
  3192.       decimal).  The return sequence is terminated by a carriage
  3193.       return.  An example of the returned text could be "1.20345".
  3194.  03   Queries extended return information.  If the file does not
  3195.       exist, a "0" is returned followed by a carriage return.  If it
  3196.       does exist, the text returned to the Host is in the Format:
  3197.       1.size.date.time <cr>.  An example of a return statement could
  3198.       be "1.20345.01/02/93.03:04:30<cr>"
  3199.  04   Queries extended return information.  If the file does not
  3200.       exist, a "0" is returned followed by a carriage return.  If it
  3201.       does exist, the text returned to the Host is in the Format:
  3202.       1.filename.size.date.time <cr>. An example of a return statement
  3203.       could be "1.MYFILE.RIP.20345.01/02/93.03:04:30 <cr>".  Note that
  3204.       the file extension adds another period into the return text.
  3205.  
  3206.  
  3207.  
  3208. ---------------------------------------------------------------------
  3209. RIP_ENTER_BLOCK_MODE
  3210. ---------------------------------------------------------------------
  3211.          Function:  Enter block transfer mode with host
  3212.             Level:  9 (system command)
  3213.           Command:  <escape>
  3214.         Arguments:  mode:1 proto:1 file_type:2 res:4
  3215.                     [filename:2] <>
  3216.            Format:  !|9<escape> <proto> <file_type> <res>
  3217.                     [filename] <>
  3218.           Example:  !|9<escape>00010000ICONFILE.ICN<>
  3219.   Uses Draw Color:  NO
  3220. Uses Line Pattern:  NO
  3221.   Uses Line Thick:  NO
  3222.   Uses Fill Color:  NO
  3223. Uses Fill Pattern:  NO
  3224.   Uses Write Mode:  NO
  3225.   Uses Font Sizes:  NO
  3226.     Uses Viewport:  NO                                                > v1.54
  3227.  
  3228. NOTE:  <escape> is used to indicate the Escape character
  3229.        (ASCII 27 or ESC).
  3230.  
  3231. This command is used to auto-initiate any desired File Transfer
  3232. Protocol.  The <filename> parameter is optional on downloads,
  3233. required for uploads, and if omitted must be replaced with a <>
  3234. parameter (end of string).
  3235.  
  3236. The <mode> parameter is to specify upload or download.  Use "1" for
  3237. upload mode, or "0" (zero) for download mode.  A filename is required
  3238. for uploads.  If the user has Data Security enabled on the terminal,
  3239. they are prompted to OK the upload before it proceeds.  If the user
  3240. does not authorize the upload, ten <Ctrl-X>'s (ASCII 24 or CAN) are
  3241. sent at one-tenth second intervals.  The <filetype> parameter is
  3242. ignored for uploads.
  3243.  
  3244. The <proto> parameter is the file transfer protocol specifier.
  3245. Possible values, and the protocols they refer to are:
  3246.  
  3247.     Value   Protocol            Filename Required?
  3248.     ----------------------------------------------
  3249.       0     Xmodem (checksum)          Yes
  3250.       1     Xmodem (CRC)               Yes
  3251.       2     Xmodem-1K                  Yes
  3252.       3     Xmodem-1K (G)              Yes
  3253.       4     Kermit                     Yes
  3254.       5     Ymodem (batch)             No
  3255.       6     Ymodem-G                   No
  3256.       7     Zmodem (crash recovery)    No
  3257.  
  3258. The <file_type> parameter determines what type of files are to be
  3259. received during the block transfer.  These are the valid parameters:
  3260.  
  3261.  
  3262.     Value   Description of Block Transfer Contents
  3263.     ---------------------------------------------------------------
  3264.       0     RIP file sequence (display it)
  3265.       1     RIP file sequence (store them)
  3266.       2     ICN file sequence (store them in proper directories)
  3267.       3     HLP file sequence (store it, and auto-load if needed)
  3268.       4     COMPOSITE DYNAMIC file sequence (batch protocols only)
  3269.       5     ACTIVE DYNAMIC file sequence (batch protocols only)
  3270.  
  3271. Whether the <filename> is specified or not, this command must have a
  3272. "<>" sequence after the filename (even if there is none).  Here are
  3273. examples of how it would look with and without a filename:
  3274.  
  3275. With a filename, using X-Modem/CRC:
  3276.  
  3277.      !|9<escape>01010000filename.icn<>
  3278.  
  3279. Without a filename, using Z-Modem
  3280.  
  3281.      !|9<escape>06040000<>
  3282.  
  3283. The special <file_type> of 4 & 5 (COMPOSITE DYNAMIC file sequences)
  3284. is somewhat different than the non-batch transfer methods.  This
  3285. allows each file uploaded to be individually processed based on their
  3286. file extensions.  If you use extensions other than .RIP or .ICN, then
  3287. this mode is not available to you as the necessary files will not be
  3288. able to be processed.  Any files that are "downloaded" from the Host
  3289. in DYNAMIC mode are placed into the appropriate sub-directories and
  3290. no further processing is performed.  .RIP files that are received are
  3291. "stored" and are not played back in COMPOSITE DYNAMIC mode.  In
  3292. ACTIVE DYNAMIC mode, they are stored and played back simultaneously.
  3293.  
  3294. NOTE:  This command must be terminated with a carriage return.
  3295.        A vertical bar (|) command delimiter cannot be used to
  3296.        separate this command from a subsequent one on the same
  3297.        line.  In other words, this command must be the last
  3298.        command on a line of text.  The protocol must begin on
  3299.        the very next line.
  3300.  
  3301.  
  3302.  
  3303. ---------------------------------------------------------------------
  3304. RIP_NO_MORE
  3305. ---------------------------------------------------------------------
  3306.          Function:  End of RIPscrip Scene
  3307.             Level:  0
  3308.           Command:  #
  3309.         Arguments:  <none>
  3310.            Format:  !|#
  3311.           Example:  !|#
  3312.   Uses Draw Color:  NO
  3313. Uses Line Pattern:  NO
  3314.   Uses Line Thick:  NO
  3315.   Uses Fill Color:  NO
  3316. Uses Fill Pattern:  NO
  3317.   Uses Write Mode:  NO
  3318.   Uses Font Sizes:  NO
  3319.     Uses Viewport:  NO                                                > v1.54
  3320.  
  3321. This command indicates that RIPscrip commands are complete.  This
  3322. allows the terminal program to activate Mouse Regions, or respond to
  3323. queued up Mouse Clicks without disturbing the natural flow of the
  3324. script transmission.
  3325.  
  3326. For noise-immunity, the Host should transmit three or more
  3327. RIP_NO_MORE command consecutively to make sure the message gets to
  3328. the terminal.  The terminal should also time-out if no data is
  3329. received for a while, and assume RIP_NO_MORE.
  3330.  
  3331. The actual duration of the "time-out" is entirely up to the           > v1.54
  3332. implementor of their terminal program.  A good recommended setting    > v1.54
  3333. would be at least an entire second or more after the receipt of the   > v1.54
  3334. last RIPscrip command.  Raw ASCII/ANSI text does not contribute to    > v1.54
  3335. the time-out in any way.  Only an actual RIPscrip command could       > v1.54
  3336. cause the time-out counter to be reset (thus starting the time-out    > v1.54
  3337. countdown all over again).  Timing-out is not a pre-requisite to      > v1.54
  3338. supporting RIPscrip.  It is a highly desirable feature to do this,    > v1.54
  3339. but it is not required.                                               > v1.54
  3340.  
  3341.  
  3342.  
  3343.  
  3344. =====================================================================
  3345. ==          HOST COMMANDS - A TUTORIAL & REFERENCE SECTION         ==
  3346. =====================================================================
  3347.  
  3348. With Mouse regions, Buttons and Text Variable Query ability, you can
  3349. control the Terminal/Paint programs and how they react with the BBS
  3350. in many ways.  To accomplish this, there are several features of
  3351. RIPscrip that permit you to do special actions based on different
  3352. circumstances.  In effect, an "action language" of sorts.  The
  3353. following sections go into the available "action language" features
  3354. in more detail.
  3355.  
  3356. Among the various abilities are:
  3357.  
  3358.      1. Control-Character specification
  3359.      2. Pre-defined Text Variables & User-defined text variables
  3360.      3. Pop-up pick-lists
  3361.      4. A Host Command "Template" system for added intelligence.
  3362.      5. Query text variable contents (pre-defined & user variables)
  3363.  
  3364.  
  3365.  
  3366.  
  3367. =====================================================================
  3368. ==                        CONTROL CHARACTERS                       ==
  3369. =====================================================================
  3370.  
  3371. Not all BBS'es will allow you to use control characters on their
  3372. Service.  Regardless of that, the capability to send any Control
  3373. Character exists for your Host Commands.  The most commonly used
  3374. Control Characters are:
  3375.  
  3376.    INDIVIDUAL CONTROL CHARACTERS         SPECIAL KEYSTROKES
  3377.    ===========================================================
  3378.    ^@ ... Null (ASCII 0)                 ^[[A ... Up Arrow
  3379.    ^G ... Beep                           ^[[B ... Down Arrow
  3380.    ^L ... Clear Screen (Top of Form)     ^[[C ... Right Arrow
  3381.    ^M ... Carriage Return                ^[[D ... Left Arrow
  3382.    ^C ... Break (sometimes)              ^[[H ... Home Key
  3383.    ^H ... Backspace                      ^[[K ... End Key
  3384.    ^[ ... Escape character               ^[[L ... Control Home
  3385.    ^S ... Pause data transmission        
  3386.    ^Q ... Resume data transmission
  3387.  
  3388. Some hosts use the ^ (caret) for their own purposes.  In these
  3389. cases, you can use the ` (backquote) character instead of the
  3390. caret.  Some systems allow you to specify the caret symbol as
  3391. two carets (^^).  Consult your Host Software documentation to
  3392. determine the best method for your needs.
  3393.  
  3394. NOTE:  RIPterm uses ^ or ` and a character to represent a control
  3395.        character.  IT IS NOT A CONTROL CHARACTER BY ITSELF, IT
  3396.        IS TRANSLATED BY RIPterm.  In other words, ^M does not send
  3397.        a ^ and then an M, it sends a carriage return (ASCII 13).
  3398.        Likewise, RIPscrip commands like Query do not use an ^[, an
  3399.        actual escape character (ASCII 27) is used.
  3400.  
  3401.  
  3402.  
  3403. =====================================================================
  3404. ==                          TEXT VARIABLES                         ==
  3405. =====================================================================
  3406.  
  3407. A special feature of RIPterm allows it to understand what a Text
  3408. Variable is.  A text variable is a piece of text that both RIPaint
  3409. and RIPterm know something about.  For example, the Text Variable
  3410. $DATE$ is known to represent the current Date on your PC.  The host
  3411. may ask your system what the values of one or more of these variables
  3412. are, and if your terminal knows these particular Text Variables, it
  3413. will tell the host.
  3414.  
  3415. There are three types of Text Variables.
  3416.  
  3417. -- Built-In Text Variables that RIPscrip products will ALWAYS
  3418.    know about.  These include Text Variables like date and time
  3419.    that return a value
  3420.  
  3421. -- Another type of built-in Text Variable are Active Text
  3422.    Variables, which perform an action, but return nothing to
  3423.    the host.  These include turning the status bar on/off,
  3424.    clearing the graphics screen, and playing some simple
  3425.    sounds, and many more.
  3426.  
  3427. -- Then there are also User Text Variables that can contain
  3428.    a variety of information depending on what the user
  3429.    entered at the time the variable was created.  For
  3430.    example, the host might ask you what the contents of the
  3431.    $FULL_NAME$ variable is, and if RIPterm doesn't know, it
  3432.    could pop-up a field on the screen and ask you about it.
  3433.    From then on, RIPterm will remember that piece of
  3434.    information for the next time it is needed by a host.
  3435.  
  3436. You may use either the pre-defined Text Variables, or the User Text
  3437. Variables at any place that allows Text Variables.
  3438.  
  3439. The following is a reference of all Built-In and Active Text
  3440. Variables.
  3441.  
  3442.  
  3443.  
  3444.  
  3445.  
  3446. The following is a Listing of the Pre-Defined Text Variables:
  3447. =============================================================
  3448.  
  3449.  
  3450.  
  3451.  
  3452. $RIPVER$ ... RIPscrip version (e.g., "RIPSCRIP015300")
  3453. ------------------------------------------------------
  3454. This Text Variable returns a phrase which will identify a
  3455. RIPscrip-compatible software package.  It is designed to be used by a
  3456. host to detect what version of RIPscrip graphics your terminal can
  3457. support as well as the type (brand) of RIPscrip terminal that is in
  3458. use.  When this Text Variable is used, it will respond back with
  3459. "RIPSCRIP" followed by the Version Number (e.g., "01.54"), followed   > v1.54
  3460. by two digits identifying the Vendor of the terminal.  The first      > v1.54
  3461. digit of the Vendor ID field is the Vendor Code (1=RIPterm).  The     > v1.54
  3462. second digit is the Vendor's sub-version code identifying sub-        > v1.54
  3463. versions of the software that still support the same RIPscrip         > v1.54
  3464. software version.  Valid Vendor Codes are:                            > v1.54
  3465.                                                                       > v1.54
  3466.      CODE   VENDOR                                                    > v1.54
  3467.      =================================================                > v1.54
  3468.        0    Generic RIPscrip terminal (vendor unknown)                > v1.54
  3469.        1    RIPterm (from TeleGrafix Communications)                  > v1.54
  3470.        2    Qmodem Pro (from Mustang Software, Inc)                   > v1.54
  3471.                                                                       > v1.54
  3472. See the section earlier in this document on ANSI sequences for a      > v1.54
  3473. more robust description of the Vendor Codes and Auto-Sensing.         > v1.54
  3474.  
  3475.      Example:  $RIPVER$
  3476.      Returns:  RIPSCRIP015300
  3477.  
  3478.  
  3479. $DATE$ ... Date in short format
  3480. -------------------------------
  3481. This Text Variable returns the current date. in the format MM/DD/YY.
  3482.  
  3483.      Example:  $DATE$
  3484.      Returns:  12/19/93
  3485.  
  3486.  
  3487.  
  3488. $MONTH$ ... Month Name
  3489. ----------------------
  3490. This Text Variable returns the full name of the current month.  It is
  3491. not abbreviated (e.g., "November" instead of "Nov")
  3492.  
  3493.      Example:  $MONTH$
  3494.      Returns:  December
  3495.  
  3496.  
  3497.  
  3498. $MONTHNUM$ ... Month Number
  3499. ---------------------------
  3500. This Text Variable returns the number of the current month.
  3501. January=01 and December=12.
  3502.  
  3503.      Example:  $MONTHNUM$
  3504.      Returns:  12
  3505.  
  3506.  
  3507.  
  3508. $DAY$ ... Day of Month Number
  3509. -----------------------------
  3510. This Text Variable returns the current day of the month.  Possible
  3511. values for this Variable are from 01-31.
  3512.  
  3513.      Example:  $DAY$
  3514.      Returns:  05
  3515.  
  3516.  
  3517.  
  3518. $DOY$ ... Day of year
  3519. ---------------------
  3520. This Text Variable returns the number of days so far in the year.  A
  3521. year has 365 days (except leap years which have 366).  $DOY$ can
  3522. return 001 - 366.
  3523.  
  3524.      Example:  $DOY$
  3525.      Returns:  214
  3526.  
  3527.  
  3528.  
  3529. $YEAR$ ... 2 digit year
  3530. -----------------------
  3531. This Text Variable returns the two-digit number of the current year.
  3532.  
  3533.      Example:  $YEAR$
  3534.      Returns:  93
  3535.  
  3536.  
  3537.  
  3538. $FYEAR$ ... 4 digit year
  3539. ------------------------
  3540. This Text Variable returns the four-digit number of the current year.
  3541.  
  3542.      Example:  $FYEAR$
  3543.      Returns:  1993
  3544.  
  3545.  
  3546.  
  3547. $TIME$ ... Time in standard format
  3548. ----------------------------------
  3549. This Text Variable returns the time in military format (hours from 00
  3550. - 23).  The format is hours, minutes, and seconds separated by
  3551. colons.  HH:MM:SS
  3552.  
  3553.      Example:  $TIME$
  3554.      Returns:  18:09:33
  3555.  
  3556.  
  3557.  
  3558. $HOUR$ ... Hour (format HH) - normal style
  3559. ------------------------------------------
  3560. This Text Variable returns the two digit number of the current hour.
  3561. This variable range from 01 - 12.  This does not use military format.
  3562.  
  3563.      Example:  $HOUR$
  3564.      Returns:  11
  3565.  
  3566.  
  3567.  
  3568. $MHOUR$ ... Hour (format HH) - military style
  3569. ---------------------------------------------
  3570. This Text Variable returns a two-digit number of the current hour in
  3571. military format.  This variable may range from 00 - 23.
  3572.  
  3573.      Example:  $MHOUR$
  3574.      Returns:  17
  3575.  
  3576.  
  3577.  
  3578. $MIN$ ... Minutes
  3579. -----------------
  3580. This Text Variable returns the two-digit number representing the
  3581. current minutes in the hour.  Possible values for this variable are
  3582. 00-59.
  3583.  
  3584.      Example:  $MIN$
  3585.      Returns:  45
  3586.  
  3587.  
  3588.  
  3589. $SEC$ ... Seconds
  3590. -----------------
  3591. This Text Variable returns a two-digit number representing the
  3592. current seconds of the minute.  Possible values for this variable are
  3593. 00-59.
  3594.  
  3595.      Example:  $SEC$
  3596.      Returns:  59
  3597.  
  3598.  
  3599.  
  3600. $AMPM$ ... Returns AM or PM depending on time
  3601. ---------------------------------------------
  3602. This Text Variable returns a two-character value of either "AM" or
  3603. "PM" depending on what time it is.
  3604.  
  3605.      Example:  $AMPM$
  3606.      Returns:  PM
  3607.  
  3608.  
  3609.  
  3610. $DATETIME$ ... Date and Time
  3611. ----------------------------
  3612. This Text Variable returns a combination date and time.  The format
  3613. is somewhat different than standard time/date notation.  It is:
  3614.  
  3615.      DAY-OF-WEEK   MONTH   DAY-OF-MONTH  HH:MM:SS  YEAR
  3616.  
  3617.      Example:  $DATETIME$
  3618.      Returns:  Sat Dec 19 14:38:50 1993
  3619.  
  3620.         NOTE:  This is the standard Unix date/time notation.
  3621.  
  3622.  
  3623.  
  3624. $TIMEZONE$ ... Time Zone or "NONE" if unknown
  3625. ---------------------------------------------
  3626. This Text Variable returns a word/phrase that describes the time-zone
  3627. the terminal is in.  This may be returned as anything like "PST" for
  3628. Pacific Standard Time, "EST" for Eastern Standard Time, etc.  If the
  3629. time zone is not set on your PC, this variable will respond with
  3630. "NONE".
  3631.  
  3632.      Example:  $TIMEZONE$
  3633.      Returns:  PST
  3634.  
  3635.  
  3636.  
  3637. $DOW$ ... Day of week fully spelled out
  3638. ---------------------------------------
  3639. This Text Variable returns the current day of the week.  The name is
  3640. fully spelled out.  Possible values are: Sunday, Monday, Tuesday,
  3641. Wednesday, Thursday, Friday and Saturday.
  3642.  
  3643.      Example:  $DOW$
  3644.      Returns:  Saturday
  3645.  
  3646.  
  3647.  
  3648. $ADOW$ ... Abbreviated Day of Week
  3649. ----------------------------------
  3650. This Text Variable returns the current day of the week in abbreviated
  3651. form.  Possible values are: Sun, Mon, Tue, Wed, Thu, Fri and Sat.
  3652.  
  3653.      Example:  $ADOW$
  3654.      Returns:  Mon
  3655.  
  3656.  
  3657.  
  3658. $WDAY$ ... Day of Week
  3659. ----------------------
  3660. This Text Variable returns a one-digit number representing the day of
  3661. the week.  Possible values are 0-6, where 0=Sunday (the first day in
  3662. the week).
  3663.  
  3664.      Example:  $WDAY$
  3665.      Returns:  2
  3666.  
  3667. $WOY$ ... Week of current year 00-53; Sunday=1st Day of Week
  3668. ------------------------------------------------------------
  3669. This Text Variable returns a number from 00-53, representing the week
  3670. in the year.  Even though there are 52 weeks in a year, a week might
  3671. not begin exactly on the first day of the year, so a maximum value
  3672. for this variable can be 53 under these circumstances.  For this
  3673. variable, Sunday is considered to be the first day of the week.
  3674.  
  3675.      Example:  $WOY$
  3676.      Returns:  32
  3677.  
  3678.  
  3679.  
  3680. $WOYM$ ... Week of current year 00-53; Monday=1st Day of Week
  3681. -------------------------------------------------------------
  3682. This Text Variable returns a number from 00-53, representing the week
  3683. in the current year.  Even though there are 52 weeks in a year, a
  3684. week might not begin exactly on the first day of the year, so a
  3685. maximum value for this variable can be 53 under these circumstances.
  3686. For this variable, Monday is considered to be the first day of the
  3687. week.
  3688.  
  3689.      Example:  $WOYM$
  3690.      Returns:  32
  3691.  
  3692.  
  3693.  
  3694. $BEEP$ ... Beep Sound (ala Ctrl-G)
  3695. ----------------------------------
  3696. This Active Text Variable beeps the terminal, producing a Ctrl-G
  3697. sound.
  3698.  
  3699. The C source code to play this sound is:
  3700.  
  3701.           sound(1000);   // the Hertz frequency to play
  3702.           delay(75);     // millisecond delay
  3703.           nosound();     // turn the sound off
  3704.           delay(75);     // millisecond delay
  3705.  
  3706.      Example:  $BEEP$
  3707.      Returns:  nothing
  3708.  
  3709.  
  3710.  
  3711. $BLIP$ ... Blipping Sound (like a hitting a barrier)
  3712. ----------------------------------------------------
  3713. This Active Text Variable is like $BEEP$, except the sound is
  3714. different.  It produces a barrier sound; like you're running into a
  3715. wall.
  3716.  
  3717. The C source code to play this sound is:
  3718.  
  3719.           sound(50);     // the Hertz frequency to play
  3720.           delay(25);     // millisecond delay
  3721.           nosound();     // turn the sound off
  3722.           delay(10);
  3723.  
  3724.      Example:  $BLIP$
  3725.      Returns:  nothing
  3726.  
  3727.  
  3728.  
  3729. $MUSIC$ ... Musical (cheerful) sound
  3730. ------------------------------------
  3731. This Active Text Variable produces a cheerful sound, indicating
  3732. success of an action.  This sound is used for successful downloads
  3733. and dialed connections.
  3734.  
  3735. The C source code to play this sound is:
  3736.  
  3737.      for (i=0 ; i<4 ; i+=1)
  3738.      {
  3739.           sound(1300);   delay(10);     // Hertz frequency to play
  3740.           sound(1200);   delay(10);     // millisecond delay
  3741.           sound(1100);   delay(10);
  3742.           sound(1000);   delay(10);
  3743.           sound(900);    delay(10);
  3744.           sound(800);    delay(10);
  3745.           sound(700);    delay(10);
  3746.           sound(850);    delay(10);
  3747.           sound(950);    delay(10);
  3748.      }
  3749.      nosound();                         // turn the sound off
  3750.  
  3751.  
  3752.      Example:  $MUSIC$
  3753.      Returns:  nothing
  3754.  
  3755.  
  3756.  
  3757. $ALARM$ ... Warning!  This sound indicates failure!
  3758. ---------------------------------------------------
  3759. This Active Text Variable produces a warning sound, indicating failure
  3760. of an action.  This sound is used for aborted downloads.
  3761.  
  3762. The C source code to play this sound is:
  3763.  
  3764.      for (i=0 ; i<3 ; i+=1)
  3765.      {
  3766.           sound(320);  delay(200);     // the Hertz frequency to play
  3767.           sound(160);  delay(425);     // millisecond delay
  3768.      }
  3769.      nosound();                        // turn the sound off
  3770.  
  3771.  
  3772.      Example:  $ALARM$
  3773.      Returns:  nothing
  3774.  
  3775.  
  3776.  
  3777. $PHASER$ ... Fire phasers!
  3778. --------------------------
  3779. This Active Text Variable produces a sound like firing your energy
  3780. weapons in a game.  Now you too can blast away with the best of them.
  3781. Trivia question:  What does phaser stand for?  See $REVPHASERS$ for
  3782. the answers.
  3783.  
  3784. The C source code to play this sound is:
  3785.  
  3786.      for (i=2500 ; i>=50 ; i-=20)
  3787.      {
  3788.           sound(i);               // the Hertz frequency to play
  3789.           delay(2);               // millisecond delay
  3790.      }
  3791.      nosound();                   // turn the sound off
  3792.  
  3793.  
  3794.      Example:  $PHASER$
  3795.      Returns:  nothing
  3796.  
  3797.  
  3798.  
  3799. $REVPHASER$ ... Fire phasers!
  3800. -----------------------------
  3801. This Active Text Variable produces a sound like firing your energy
  3802. weapons in a game.  Like $PHASER$ makes an ascending tone,
  3803. $REVPHASER$ makes a descending tone.  Answer to trivia question in
  3804. $PHASER$: Phaser stands for PHoton Amplification by Stimulated
  3805. Emission of Radiation.  Sound familiar?  Laser is Light Amplification
  3806. by Stimulated Emission of Radiation, and Maser is Microwave
  3807. Amplification by Stimulated Emission of Radiation.
  3808.  
  3809. The C source code to play this sound is:
  3810.  
  3811.           for (i=50 ; i<=2500 ; i+=20)
  3812.           {
  3813.                sound(i);               // the Hertz frequency to play
  3814.                delay(2);               // millisecond delay
  3815.           }
  3816.           nosound();                   // turn the sound off
  3817.  
  3818.      Example:  $REVPHASER$
  3819.      Returns:  nothing
  3820.  
  3821.  
  3822.  
  3823. $X$ ... X Mouse location
  3824. ------------------------
  3825. This Text Variable returns the current X coordinate of the mouse
  3826. pointer.  This can be used interactively (for example, by on-line
  3827. games) to determine the location of the mouse pointer.  Only the X
  3828. value of the mouse (X,Y) is returned.  The value is 0000-9999
  3829. depending on what the current position is.
  3830.  
  3831.      Example:  $X$
  3832.      Returns:  0523
  3833.  
  3834.  
  3835.  
  3836. $Y$ ... Y Mouse location
  3837. ------------------------
  3838. This Text Variable returns the current Y coordinate of the mouse
  3839. pointer.  This can be used interactively (for example, by on-line
  3840. games) to determine the location of the mouse pointer.  Only the Y
  3841. value of the Mouse (X,Y) is returned.  The value is 0000-9999
  3842. depending on what the current position is.
  3843.  
  3844.      Example:  $Y$
  3845.      Returns:  0244
  3846.  
  3847.  
  3848.  
  3849. $XY$ ... X/Y Mouse Location
  3850. ---------------------------
  3851. This Text Variable returns both the X and Y coordinates of the mouse
  3852. pointer.  A colon (:) separates the two values.  The X and Y values
  3853. may range from 0000-9999.  The format that this value uses is:
  3854. XXXX:YYYY
  3855.  
  3856.      Example:  $XY$
  3857.      Returns:  0297:0321
  3858.  
  3859.  
  3860.  
  3861. $XYM$ ... X, Y & button status
  3862. ------------------------------
  3863. This Text Variable returns the X and Y coordinates of the mouse
  3864. pointer, and which mouse buttons are pressed (if any).  A colon (:)
  3865. separates the three values.  The X and Y values may range from
  3866. 0000-9999.  LMR stands for Left/Middle/Right.  If any of these
  3867. buttons are depressed (clicked), then the corresponding position will
  3868. contain a 1.  If a button is NOT depressed, then it will contain a
  3869. 0.  The format that this value uses is:  XXXX:YYYY:LMR
  3870.  
  3871. This means that the (X,Y) location of the cursor is (0123,0297), and
  3872. that the Left and Middle buttons are depressed, but that the Right
  3873. Mouse Button is not depressed.
  3874.  
  3875.      Example:  $XYM$
  3876.      Returns:  0123:0297:110
  3877.  
  3878.  
  3879.  
  3880. $M$ ... Mouse Button Status: LMR
  3881. --------------------------------
  3882. This Text Variable returns a 3-character code representing the status
  3883. of each mouse button.  This variable works with two button and three
  3884. button mice.  The format of the code is LMR where L=Left, M=Middle
  3885. (if any), and R=Right.  If any button is clicked, the code for that
  3886. button is "1".  If the button is not depressed, it is "0".  "100"
  3887. would mean the left mouse button is depressed, but none of the others
  3888. are.
  3889.  
  3890.      Example:  $M$
  3891.      Returns:  001
  3892.  
  3893.  
  3894.  
  3895. $MSTAT$ ... Mouse Status
  3896. ------------------------
  3897. This Text Variable returns a "YES" if there is a mouse installed on
  3898. the RIPterm computer.  If no mouse is installed, this variable
  3899. returns "NO".
  3900.  
  3901.      Example:  $MSTAT$
  3902.      Returns:  YES
  3903.  
  3904.  
  3905.  
  3906. $RESET$ ... Performs RIP_RESET_WINDOWS (Identical to !|*)
  3907. ---------------------------------------------------------
  3908. This Active Text Variable resets and clears the graphics screen,
  3909. resets the text window to full screen and clears it, resets the color
  3910. palette, deletes all mouse fields, and clears the clipboard.
  3911.  
  3912.      Example:  $RESET$
  3913.      Returns:  nothing
  3914.  
  3915.  
  3916.  
  3917. $SAVEALL$ ... Save all screen attributes
  3918. ----------------------------------------
  3919. This Active Text Variable saves the Text Windows coordinates, save
  3920. the contents of the clipboard, saves all mouse fields, and saves the
  3921. contents of the entire screen.  It is the same as doing a "$STW$
  3922. $SCB$ $SMF$ $SAVE$".
  3923.  
  3924.      Example:  $SAVEALL$
  3925.      Returns:  nothing
  3926.  
  3927.  
  3928.  
  3929. $RESTOREALL$ ... Restore all screen attributes
  3930. ----------------------------------------------
  3931. This Active Text Variable restores the Text Windows coordinates,
  3932. restores the contents of the clipboard, restores all mouse fields,
  3933. and restores the contents of the screen.  It is equal to "$RTW$ $RCB$
  3934. $RMF$ $RESTORE$".
  3935.  
  3936.      Example:  $RESTOREALL$
  3937.      Returns:  nothing
  3938.  
  3939.  
  3940.  
  3941. $EGW$ ... Erase Graphics Window
  3942. -------------------------------
  3943. This Active Text Variable erases the graphics window (much like a
  3944. Reset Windows command does). This command is useful in Host
  3945. Commands.  When you click on a Mouse Field, it could erase the
  3946. graphics window THEN transmit the remainder of the return string (if
  3947. any) to the host.
  3948.  
  3949. Remember, this may not clear the entire screen (although it will
  3950. quite often since the Graphical Viewport is often full-screen).
  3951.  
  3952.      Example:  $EGW$
  3953.      Returns:  nothing
  3954.  
  3955.  
  3956.  
  3957. $SAVE$ and $SAVEx$ ... Save graphics screen
  3958. -------------------------------------------
  3959. The Active Text Variable $SAVE$ saves the contents of the entire
  3960. graphics screen to a disk file called RIPTERM.SAV.  No Mouse Fields,
  3961. Text Window locations or Clipboard data are saved - just the graphics
  3962. screen.  The entire 640x350 region is saved to disk.
  3963.  
  3964. If you choose the SAVE0 through SAVE9 variations, the filename that
  3965. is saved to files RIPTERM0.SAV through RIPTERM9.SAV, allowing you to
  3966. have multiple screens saved simultaneously.
  3967.  
  3968. In addition to the Graphical data that is currently on-screen, the    > v1.54
  3969. current Graphical Viewport settings are saved as well so that when a  > v1.54
  3970. restore is done, the viewport will be properly restored as well.      > v1.54
  3971.  
  3972. If you wish to save the entire state of the RIPterm system, use
  3973. $SAVEALL$.
  3974.  
  3975.      Example:  $SAVE7$
  3976.      Returns:  nothing
  3977.  
  3978.  
  3979.  
  3980. $RESTORE$ and $RESTOREx$ ... Restore graphics screen
  3981. ----------------------------------------------------
  3982. The Active Text Variable $RESTORE$ reads the saved file RIPTERM.SAV
  3983. in from disk and restores the graphics as they were originally saved
  3984. with the $SAVE$ command.  Only the graphics screen is restored, not
  3985. the Clipboard, Mouse Fields or Text Window settings.
  3986.  
  3987. If you choose the RESTORE0 through RESTORE9 variations, the filename
  3988. that is restored are RIPTERM0.SAV through RIPTERM9.SAV, allowing you
  3989. to restore from up to ten different saved files.  A slight difference
  3990. from $RESTORE$ is that $RESTORE0$ - $RESTORE9$ delete the file after
  3991. the graphics screen is restored.
  3992.  
  3993. When the graphics screen is restored, the Graphics Viewport settings  > v1.54
  3994. that were in effect when the screen was saved will be restored as     > v1.54
  3995. well.                                                                 > v1.54
  3996.  
  3997. To restore the entire context of the graphics environment $RESTALL$.
  3998.  
  3999.      Example:  $RESTORE3$
  4000.      Returns:  nothing
  4001.  
  4002.  
  4003.  
  4004. $SMF$ ... Save Mouse Fields
  4005. ---------------------------
  4006. This Active Text Variable saves all defined Mouse Fields and Mouse
  4007. Buttons to a temporary file for later retrieval.  This is designed
  4008. especially for the graphical designer who wishes to pop-up a dialog
  4009. box on the screen with one or more mouse fields, and when finished,
  4010. to restore the screen and original mouse fields.  This command is
  4011. intended to be used with the Restore Mouse Fields text variable
  4012. $RMF$.
  4013.  
  4014.      Example:  $SMF$
  4015.      Returns:  nothing
  4016.  
  4017.  
  4018.  
  4019. $RMF$ ... Restore Mouse Fields
  4020. ------------------------------
  4021. This Active Text Variable restores any Mouse Fields saved with $SMF$.
  4022. You may have only one set of mouse fields saved at once.  If no mouse
  4023. fields were saved, or if the number of fields saved is 0, then no
  4024. mouse fields are  active.
  4025.  
  4026. NOTE:  You may restore Mouse Fields more than once is you wish. In
  4027.        other words, if you do a $SMF$ command, you may execute
  4028.        $RMF$ one or more times.
  4029.  
  4030.      Example:  $RMF$
  4031.      Returns:  nothing
  4032.  
  4033.  
  4034.  
  4035. $MKILL$ ... Kill Mouse Fields
  4036. -----------------------------
  4037. This Active Text Variable deletes all defined Mouse Fields exactly
  4038. like RIP_KILL_MOUSE_FIELDS does.  The benefit is when the user clicks
  4039. on a Mouse Fields or Button, the Mouse Fields are removed, but the
  4040. graphics remain on the screen.  The fields could be subsequently
  4041. re-defined quickly and easily without having to re-transmit an
  4042. identical menu over again.
  4043.  
  4044.      Example:  $MKILL$
  4045.      Returns:  nothing
  4046.  
  4047.  
  4048.  
  4049. $ETW$ ... Erase Text Window
  4050. ---------------------------
  4051. This Active Text Variable erases the Text Window (like a clear screen
  4052. code does).  This command is useful in Host Commands when you click on
  4053. a Mouse Field, it could erase the text window THEN transmit the
  4054. remainder of the Host Command (if any).
  4055.  
  4056.      Example:  $ETW$
  4057.      Returns:  nothing
  4058.  
  4059.  
  4060.  
  4061. $DTW$ ... Disable Text Window
  4062. -----------------------------
  4063. This Active Text Variable disables the Text Window (preventing any
  4064. received text from showing up on screen).  This command is useful in
  4065. Host Commands when you click on a Mouse Field, it would halt any
  4066. further output to the text window.
  4067.  
  4068.      Example:  $DTW$
  4069.      Returns:  nothing
  4070.  
  4071.  
  4072.  
  4073. $STW$ ... Save Text Window information
  4074. --------------------------------------
  4075. This Active Text Variable stores all of the text window settings.
  4076. The window's X/Y dimensions are preserved, as is the current cursor
  4077. location, ANSI attributes, cursor ON/OFF status and the vertical
  4078. scrolling margins.  Even the current System Font is saved (if
  4079. necessary).
  4080.  
  4081. NOTE:  The contents of the Text Window are NOT saved.
  4082.  
  4083.      Example:  $STW$
  4084.      Returns:  nothing
  4085.  
  4086.  
  4087.  
  4088. $RTW$ ... Restore Text Window information
  4089. -----------------------------------------
  4090. This Active Text Variable restores the Text Window to the settings
  4091. active when $STW$ (Save Text Window) was executed. The current cursor
  4092. location, ANSI attributes, cursor ON/OFF status, vertical scrolling
  4093. margins, and the System Font are restored.
  4094.  
  4095. NOTE:  The text contents of the window are not restored.
  4096.  
  4097.      Example:  $RTW$
  4098.      Returns:  nothing
  4099.  
  4100.  
  4101.  
  4102. $TWIN$ ... Text  Window Status
  4103. ------------------------------
  4104. This Text Variable checks to see if a Text Window exists, and returns
  4105. YES if there is a Text Window, or returns NO if there is no Text
  4106. Window or the Text Window has been disabled (with $DTW$).
  4107.  
  4108.      Example:  $TWIN$
  4109.      Returns:  YES
  4110.  
  4111.  
  4112.  
  4113. $TWFONT$ ... Active Text Font
  4114. -----------------------------
  4115. This Text Variable returns which of the five Text Window Fonts is
  4116. active, or 0 (zero) if there is no Text Window.
  4117.  
  4118.           0 ... No Text Window          3 ... 80x25 font
  4119.           1 ... 80x43 font              4 ... 91x25 MicroANSI font
  4120.           2 ... 91x43 MicroANSI font    5 ... 40x25 font
  4121.  
  4122.      Example:  $TWFONT$
  4123.      Returns:  1
  4124.  
  4125.  
  4126.  
  4127. $TWH$ ... Text Window Height
  4128. ----------------------------
  4129. This Text Variable returns the height of the Text Window, or 0 (zero)
  4130. if there is no Text Window.  If a text window exists, the minimum
  4131. value is 1 and the maximum value is 43.  This may increase in the
  4132. future.
  4133.  
  4134.      Example:  $TWH$
  4135.      Returns:  25
  4136.  
  4137.  
  4138.  
  4139. $TWW$ ... Text Window Width
  4140. ---------------------------
  4141. This Text Variable returns the width of the Text Window, or 0 (zero)
  4142. if there is no Text Window.  If a text window exists, the minimum
  4143. value is 1 and the maximum value is 91.  This may increase in the
  4144. future.
  4145.  
  4146.      Example:  $TWW$
  4147.      Returns:  80
  4148.  
  4149.  
  4150.  
  4151. $TWX0$ ... Text Window Upper Left X Coordinate
  4152. ----------------------------------------------
  4153. This Text Variable is the X coordinate of the upper left corner of
  4154. the Text Window.  The coordinates given are relative to the upper
  4155. left of the screen.  The values are given in cells, which is a block
  4156. the size of one character in the currently selected font.  A good
  4157. analogy is that a cell is equivalent to a square on a sheet of graph
  4158. paper.  The cell size may change depending on the font used, but the
  4159. relative position for that font remains constant.  If there is no
  4160. Text Window, this returns 0 (zero).  However, note that 0 (zero) is
  4161. also a valid coordinate.  Use $TWIN$ to determine if there is a Text
  4162. Window.
  4163.  
  4164.      Example:  $TWX0$
  4165.      Returns:  0
  4166.  
  4167.  
  4168.  
  4169. $TWY0$ ... Text Window Upper Left Y Coordinate
  4170. ----------------------------------------------
  4171. This Text Variable is the Y coordinate of the upper left corner of
  4172. the Text Window.  See $TWX0$ for an explanation of the coordinate
  4173. system.
  4174.  
  4175.      Example:  $TWY0$
  4176.      Returns:  40
  4177.  
  4178.  
  4179.  
  4180. $TWX1$ ... Text Window Lower Right X Coordinate
  4181. -----------------------------------------------
  4182. This Text Variable is the X coordinate of the lower right corner of
  4183. the Text Window.  See $TWX0$ for an explanation of the coordinate
  4184. system.
  4185.  
  4186.      Example:  $TWX1$
  4187.      Returns:  80
  4188.  
  4189.  
  4190.  
  4191. $TWY1$ ... Text Window Lower Right Y Coordinate
  4192. -----------------------------------------------
  4193. This Text Variable is the Y coordinate of the lower right corner of
  4194. the Text Window.  See $TWX0$ for an explanation of the coordinate
  4195. system.
  4196.  
  4197.      Example:  $TWY1$
  4198.      Returns:  43
  4199.  
  4200.  
  4201.  
  4202. $CURX$ ... Text Cursor X Coordinate
  4203. -----------------------------------
  4204. This Text Variable is the X coordinate of the text cursor in the Text
  4205. Window, relative to the upper left of the Text Window.  See $TWX0$ for
  4206. an explanation of the coordinate system.
  4207.  
  4208.      Example:  $CURX$
  4209.      Returns:  2
  4210.  
  4211.  
  4212.  
  4213. $CURY$ ... Text Cursor Y Coordinate
  4214. -----------------------------------
  4215. This Text Variable is the Y coordinate of the text cursor in the Text
  4216. Window, relative to the upper left of the Text Window.  See $TWX0$ for
  4217. an explanation of the coordinate system.
  4218.  
  4219.      Example:  $CURY$
  4220.      Returns:  5
  4221.  
  4222.  
  4223.  
  4224. $CON$ ... Enable the Text Cursor
  4225. --------------------------------
  4226. This Active Text Variable turns on the text cursor.
  4227.  
  4228.      Example:  $CON$
  4229.      Returns:  nothing
  4230.  
  4231.  
  4232.  
  4233. $COFF$ ... Disable the Text Cursor
  4234. ----------------------------------
  4235. This Active Text Variable turns off the text cursor.  This is
  4236. automatically reset when a Reset Windows command is received.
  4237.  
  4238.      Example:  $COFF$
  4239.      Returns:  nothing
  4240.  
  4241.  
  4242.  
  4243. $CURSOR$ ... Text Cursor Status
  4244. -------------------------------
  4245. This Text Variable returns YES if the Text Cursor is enabled, and NO
  4246. if the Text Cursor is disabled.  If there no Text Window, it returns
  4247. NO.
  4248.  
  4249.      Example:  $CURSOR$
  4250.      Returns:  YES
  4251.  
  4252.  
  4253.  
  4254. $SCB$ ... Save Clipboard
  4255. ------------------------
  4256. This Active Text Variable saves the Clipboard to disk for later
  4257. retrieval by a Query or Host Command.  If the clipboard is empty, the
  4258. temporary file is deleted so Restore Clipboard knows there shouldn't
  4259. be a clipboard active.
  4260.  
  4261.      Example:  $SCB$
  4262.      Returns:  nothing
  4263.  
  4264.  
  4265.  
  4266. $RCB$ ... Restore Clipboard
  4267. ---------------------------
  4268. This Active Text Variable restores the Clipboard from the temporary
  4269. disk file called RIPCLIB.BRD.  This file is created by $SCB$ (Save
  4270. Clipboard).  Not only are the clipboard contents saved, but so is the
  4271. last clipboard location, so Paste Clipboard ($PCB$) restores the
  4272. clipboard's contents AND location.
  4273.  
  4274.      Example:  $RCB$
  4275.      Returns:  nothing
  4276.  
  4277.  
  4278.  
  4279. $PCB$ ... Paste Clipboard at last location
  4280. ------------------------------------------
  4281. This Active Text Variable pastes the clipboard at the last location
  4282. it was clipped from. This also works with icons.  The last location
  4283. taken used is the location the icon was stamped when it was first
  4284. loaded.  This text variable is useful if you want to pop up a dialog
  4285. box (saving the previous area behind the dialog onto the clipboard),
  4286. and when the user clicks on the "OK" button, restoring the screen
  4287. contents (by using a $PCB$ in the host command string).
  4288.  
  4289. When the Clipboard is pasted back onto the screen, it adheres to the  > v1.54
  4290. Graphical Viewport that was in effect when the clipboard was clipped  > v1.54
  4291. initially.  In other words, the clipboard will be put in the same     > v1.54
  4292. location regardless of where it came from.                            > v1.54
  4293.  
  4294.      Example:  $PCB$
  4295.      Returns:  nothing
  4296.  
  4297.  
  4298.  
  4299. $STATBAR$ ... Status Bar Status
  4300. -------------------------------
  4301. This Text Variable returns YES if the Status Bar is visible in the
  4302. terminal.  If the Status Bar is not visible, then NO is returned.
  4303.  
  4304.      Example:  $STATBAR$
  4305.      Returns:  YES
  4306.  
  4307.  
  4308.  
  4309. $SBARON$ ... Turn ON the Status Bar
  4310. -----------------------------------
  4311. This Active Text Variable turns ON the Status Bar in the terminal.
  4312.  
  4313.      Example:  $SBARON$
  4314.      Returns:  nothing
  4315.  
  4316.  
  4317.  
  4318. $SBAROFF$ ... Turn OFF the Status Bar
  4319. -------------------------------------
  4320. This Active Text Variable turns OFF the Status Bar in the terminal.
  4321.  
  4322.      Example:  $SBAROFF$
  4323.      Returns:  nothing
  4324.  
  4325.  
  4326.  
  4327. $VT102ON$ ... Turn VT-102 keyboard mode ON
  4328. ------------------------------------------
  4329. This Active Text Variable enables the VT-102 keystrokes ability.
  4330. This makes the following keystrokes send something to the host:
  4331.  
  4332.                   F1 - ESC [ M
  4333.                   F2 - ESC [ N
  4334.                   F3 - ESC [ O
  4335.                   F4 - ESC [ P
  4336.                   F5 - ESC [ Q
  4337.                   F6 - ESC [ R
  4338.                   F7 - ESC [ S
  4339.                   F8 - ESC [ T
  4340.                   F9 - ESC [ U
  4341.                  F10 - ESC [ V
  4342.                 PGUP - ESC [ I
  4343.                 PGDN - ESC [ G
  4344.                 HOME - ESC [ H
  4345.                  END - ESC [ F
  4346.               INSERT - ESC [ L
  4347.            CURSOR UP - ESC [ A
  4348.            CURSOR DN - ESC [ B
  4349.          CURSOR LEFT - ESC [ C
  4350.         CURSOR RIGHT - ESC [ D
  4351.  
  4352. This text variable puts the terminal in VT-102 mode automatically,
  4353. making it simpler for the user.
  4354.  
  4355.      Example:  $VT102ON$
  4356.      Returns:  nothing
  4357.  
  4358.  
  4359.  
  4360. $VT102OFF$ ... Turn VT-102 keyboard mode OFF
  4361. --------------------------------------------
  4362. This Active Text Variable disables the VT-102 keystrokes mode,
  4363. returning your keyboard to the standard keyboard operation.
  4364.  
  4365.      Example:  $VT102OFF$
  4366.      Returns:  nothing
  4367.  
  4368.  
  4369.  
  4370. $DWAYON$ ... Turn Doorway Mode ON
  4371. ---------------------------------
  4372. This Active Text Variable enables Doorway Mode.  This is intended to
  4373. be used by a Host system that wishes to take advantage of the Doorway
  4374. mode available in Marshall Dudley's Doorway (tm) software package.
  4375.  
  4376.      Example:  $DWAYON$
  4377.      Returns:  nothing
  4378.  
  4379.  
  4380.  
  4381. $DWAYOFF$ ... Turn Doorway Mode OFF
  4382. -----------------------------------
  4383. This Active Text Variable disables the Doorway keyboard mode.  This
  4384. will return the keyboard to normal operation.
  4385.  
  4386.      Example:  $DWAYOFF$
  4387.      Returns:  nothing
  4388.  
  4389.  
  4390.  
  4391. $HKEYON$ ... Enable Button Hotkeys
  4392. ----------------------------------
  4393. This Active Text Variable turns on use of Button Hotkeys.  When
  4394. enabled, if the user presses a key associated with a button, it is
  4395. selected just as if it were clicked.  The Scroll Lock light on the
  4396. keyboard is turned on.
  4397.  
  4398.      Example:  $HKEYON$
  4399.      Returns:  nothing
  4400.  
  4401.  
  4402.  
  4403. $HKEYOFF$ ... Disable Button Hotkeys
  4404. ------------------------------------
  4405. This Active Text Variable turns off Button Hotkeys.  This should be
  4406. done when entering a full-screen editor, or any part of the system
  4407. where the user is entering a string of text.  This is to prevent the
  4408. user from accidentally selecting a button when typing in text.
  4409.  
  4410.      Example:  $HKEYOFF$
  4411.      Returns:  nothing
  4412.  
  4413.  
  4414.  
  4415. $TABON$ ... Enable TAB key Mouse Field select
  4416. ---------------------------------------------
  4417. This Active Text Variable turns on the use of the TAB key to jump
  4418. from one defined Mouse or Button Field to another.
  4419.  
  4420.      Example:  $TABON$
  4421.      Returns:  nothing
  4422.  
  4423.  
  4424.  
  4425. $TABOFF$ ... Disable TAB key Mouse Field select
  4426. -----------------------------------------------
  4427. This Active Text Variable turns off the use of the TAB key to jump
  4428. from one defined Mouse or Button Field to another.  If this command
  4429. is received when a field is highlighted, it is deselected.  This
  4430. should be done when entering a full-screen editor so that the user
  4431. can use the TAB key as a TAB, not a Mouse Field selector.
  4432.  
  4433.      Example:  $TABOFF$
  4434.      Returns:  nothing
  4435.  
  4436.  
  4437.  
  4438. $APP0$ - $APP9$ ... External Application Call
  4439. -----------------------------------------------
  4440. This Active Text Variable instructs the terminal to execute an
  4441. external application.  By recommendation, $APP0$ is the user's text
  4442. editor.  There are ten external application slots available, numbered
  4443. 0 - 9.  These are defined in the External menu in RIPterm.
  4444.  
  4445.      Example:  $APP1$
  4446.      Returns:  nothing
  4447.  
  4448.  
  4449.  
  4450.  
  4451. =====================================================================
  4452. ==                 LOCAL RIPscrip FILE PLAYBACK                    ==
  4453. =====================================================================
  4454.  
  4455.  
  4456. You can re-play a .RIP file that you have locally on your hard disk
  4457. from anyplace that allows text variables.  The format of the variable
  4458. is somewhat different than user variables, or pre-defined text
  4459. variables.  After the initial dollar sign ($), enter the greater-than
  4460. symbol (>) followed by the filename (with or without the .RIP
  4461. extension), then ending in another dollar sign ($).  Several examples
  4462. of this are as follows:
  4463.  
  4464.          $>MYFILE.RIP$
  4465.          $>FILE1$
  4466.          $>FILE1.RIP$$>FILE2.RIP$$>FILE3$
  4467.  
  4468. Note in the last example, a file extension other than .RIP was used.
  4469. You are not limited to playing back local .RIP files.  In fact, you
  4470. can play-back any file you want.  You could load any simple text
  4471. file, ANSI picture image, or other such thing.  When loaded, the data
  4472. is not sent to the host; it is strictly echoed on your local screen.
  4473. If the file is a .RIP file, it will replay any graphics that were in
  4474. the file and if any Mouse Regions are defined, it will create those
  4475. fields for you as well, thus allowing you to pop-up dialog screens or
  4476. other such things that are not built-in to RIPterm normally.
  4477.  
  4478. Each "local RIP playback" variable you enter will search for the .RIP
  4479. file in the current host's icon directory.  If it cannot find the
  4480. file in that directory, it will check the ICONS\ directory.
  4481.  
  4482.  
  4483.  
  4484.  
  4485.  
  4486. =====================================================================
  4487. ==                           POP-UP LISTS                          ==
  4488. =====================================================================
  4489.  
  4490. Any place that you can use a Text Variable (Queries, Button and Mouse
  4491. Field return strings, and Keystroke Macros), you can take advantage of
  4492. a unique feature of RIPscrip - Pop-Up Pick Lists.  A Pop-Up Pick List
  4493. is simply a list that pops up allowing you to choose from one of
  4494. several available values.  Whichever entry in the list you choose
  4495. will insert it's associated command in the Host Command returned back
  4496. to your host.
  4497.  
  4498. A list is created by putting the special list instructions inside two
  4499. sets of parenthesis like this: (( and )).  The list consists of an
  4500. optional question followed by two colons (::), followed by one or
  4501. more list entries.  For example, ((Send Email
  4502. to?::Sysop,Cosysop,Joe)) says to pop-up a list asking you "Send Email
  4503. to?", giving you the choices of "Sysop", "Cosysop", and "Joe".
  4504.  
  4505. By default, if you press ESC instead of picking an entry in the list,
  4506. then nothing will be inserted into the text of your Command. You can
  4507. indicate that the user must pick an entry by putting an asterisk (*)
  4508. at the beginning of the question.  For example, ((*Send Mail
  4509. to?::Sysop,Joe)).  This would make it so that the user must choose
  4510. either Sysop or Joe.
  4511.  
  4512. In the previous examples, Sysop and Joe are the text responses that
  4513. are inserted into your Host Command.  These commands are also the
  4514. same things that are displayed in the listing.  If you want to use
  4515. something else in the listing instead of the return text, you can.
  4516. When you make the list entry, add an @description to the end of it.
  4517. For example:
  4518.  
  4519.      ((Send Mail To?::Sysop@Head Honcho,Cosysop,Joe))
  4520.  
  4521. ...would display a pop-up pick list of Head Honcho, Cosysop, and Joe.
  4522.  
  4523. One final feature of Pop-Up Pick Lists allows you to specify a hotkey
  4524. for each entry in the list.  For example, if you wanted the first
  4525. character of each entry to be highlighted (thus allowing you to
  4526. select that character to activate the entry), simply put a tilde (~)
  4527. or an underline (_) before and after the keystroke.  For example
  4528. "_S_ysop" would highlight the "S" in "Sysop" appearing like this:
  4529.  
  4530.                        Sysop
  4531.  
  4532. You can highlight more than one character, but only the first one will
  4533. be the active hotkey.  If you omit the second tilde or underline,
  4534. then the remainder of the description will be highlighted.
  4535.  
  4536. NOTE:  If you use a tilde or an underline in the Text Response (not
  4537.        the description), then those characters are inserted into
  4538.        your Host Command when it is transmitted to the host.  You
  4539.        probably don't want to do this.  Recommendation: only use
  4540.        hotkey features on list entries where you specify a
  4541.        description!
  4542.  
  4543. If you do not specify a question, then the list default to the
  4544. question:
  4545.  
  4546.                Choose one of the following:
  4547.  
  4548. You may specify up to twenty entries for any one list.  In RIPterm    > v1.53
  4549. version 1.52 and earlier, the total length of a pick list was 256     > v1.53
  4550. bytes.  In version 1.53 and later, this limit has been increased to   > v1.53
  4551. 1024 bytes.                                                           > v1.53
  4552.  
  4553. Some characters have special significance in the RIPscrip language.
  4554. These characters are ! (exclamation mark, or for you Unix-heads,
  4555. bang), \ (backslash), and | (vertical bar).  To use these characters
  4556. in a Text Response, they must be preceded by a backslash (! becomes
  4557. \!, \ becomes \\, and | becomes \|).  RIPaint automatically adds
  4558. these when creating Text Responses.  You need to be aware of this
  4559. only if you are editing RIPscrip files with a text editor.  The _
  4560. (underline) and ~ (tilde) characters used to indicate the hotkey in a
  4561. Text Response are not able to be preceded by a backslash to be used
  4562. by themselves.  They will be returned to the host if they exist in a
  4563. Text Response (not in the description), however everything after the
  4564. underline or tilde will be underlined, and the first character will
  4565. be considered the hotkey.
  4566.  
  4567.   Examples:
  4568.  
  4569.      ((Send E-Mail to?::Sysop,Joe,Mike))
  4570.      ((*Send E-Mail to?::Sysop@The Head Honcho,Joe,Mike@My Brother))
  4571.      ((::Sysop@_T_he Head Honcho,Joe,Mike@My _B_rother))
  4572.  
  4573.  
  4574.  
  4575.  
  4576.  
  4577. =====================================================================
  4578. ==                     HOST COMMAND "TEMPLATES"                    ==
  4579. =====================================================================
  4580.  
  4581. Often you might want a button on your screen to do one thing in one
  4582. situation, but to do something completely different in another
  4583. situation.  In the past, this required having a separate menu file
  4584. for each different function that this Button needs.  This cumbersome
  4585. method is history with Command Templates.
  4586.  
  4587. Command Templates are probably best described with a brief example.
  4588. Lets say that you have a menu screen for reading and writing messages
  4589. in your public message forums.  On this menu, you can have buttons
  4590. for each forum on your host, and at the same time have buttons for
  4591. Read, Write, Erase, Modify, etc.  Now, how can you make the
  4592. Read/Write/etc.  buttons work differently for each forum button
  4593. clicked?
  4594.  
  4595.                   Templates!
  4596.  
  4597. To further refine our example, lets say that you click on the button
  4598. for Forum #1, it should send the command "S FORUM1" to the host to
  4599. select that forum.  After that, simply clicking on the Read or Write
  4600. buttons will read through the current section.  But, what if you want
  4601. to interactively move about on the menu? Make each of the forum
  4602. selection buttons define a template.  Each template instructs
  4603. RIPscrip how to process the other buttons.
  4604.  
  4605. In the example above, the Forum #1 button would define this template:
  4606.  
  4607.                 S FORUM1 $?$^m
  4608.  
  4609. This template will return "S FORUM1" followed by the Host Command for
  4610. whichever button is clicked, followed by a carriage return. The
  4611. special text variable $?$ is only used in Command Templates, and is
  4612. used to indicate "insert the text into the template here".  It
  4613. references the text of some other button that was clicked that is
  4614. stuffing its data INTO this template.
  4615.  
  4616.  
  4617. CHARACTERISTICS OF TEMPLATES
  4618. ----------------------------
  4619. Before you can go about defining templates, you need to know how they
  4620. work, interact and how other functions interact with templates.
  4621.  
  4622. You are allowed up to 36 different templates, each of which can be
  4623. different and active at the same time.  Each template corresponds to a
  4624. Button Group (see MOUSE FIELDS AND BUTTONS for more detail).  Templates
  4625. can be defined and/or activated in any order.  In other words, you can
  4626. have a template #1, 5, 13 and 32, but none of the others defined.
  4627. Templates remain defined until re-defined by another template.
  4628.  
  4629.  
  4630. DEFINING A TEMPLATE
  4631. -------------------
  4632. To create a template, when asked for a Host Command, simply type in
  4633. the Template similar to the following:
  4634.  
  4635.      [5:]S FORUM1 $?$^m
  4636.  
  4637. The [5:] at the beginning of the command indicates that you wish to
  4638. create template #5 with the following text as the template.  Remember,
  4639. a $?$ is considered a "macro" that will insert some text into this
  4640. template from another source.  Valid template numbers are 0-9, A-Z.
  4641. So, with this in mind, all of the following template definitions are
  4642. valid:
  4643.  
  4644.      [0:]S FORUM1 $?$^m
  4645.      [9:]S FORUM2 $?$^m
  4646.      [G:]S FORUM3 $?$^m
  4647.  
  4648.  
  4649. USING TEMPLATES
  4650. ---------------
  4651. When you want to make a button "feed its command" into a template, you
  4652. do so in a format similar to defining a Template, but with a subtle
  4653. difference.  Don't include the colon (:) in the template reference.
  4654. An example of this would be the following:
  4655.  
  4656.      [0]HELLO
  4657.  
  4658. This says, take the text "HELLO" and feed it into template number 0,
  4659. and send the final result to the host.  Note how simple it is to
  4660. create and reference templates by either using a colon or omitting
  4661. it.
  4662.  
  4663. If you do not specify a Template reference in the format [#] at the
  4664. beginning of your Host Command, it will be considered to be a Normal
  4665. Host Command that does not get stuffed into any templates.  For
  4666. completeness, you may specify []HELLO to send the word "HELLO" to the
  4667. host without going through any templates (a "null" template).  So in
  4668. other words, using a [] or using nothing at all is the same thing,
  4669. don't use any templates for this host command.
  4670.  
  4671.  
  4672. CHAINING TEMPLATE RESPONSES
  4673. ---------------------------
  4674. In the preceding examples we showed how you can feed the Host Command
  4675. of one button through a single Template definition.  This is the
  4676. simplest case of template processing.  As part of the big picture of
  4677. templates, you can chain the input of one template into another
  4678. template, into another, so on and so forth and then transmit the
  4679. result of all composite template stuffing to the Host as one big
  4680. command.  After all is said and done with template processing, the
  4681. text buffer sent to the host can be anywhere from 0-4095 characters
  4682. in length.
  4683.  
  4684. To chain one template into another, use a format similar to the
  4685. following:
  4686.  
  4687.      [0372]HELLO
  4688.  
  4689. This feeds the word "HELLO" into template #0, then that result into
  4690. template #3, then that result into template #7, then finally the
  4691. result will be stuffed into Template #2. The output from Template #2
  4692. will then be transmitted to the host.
  4693.  
  4694. You may specify from 0-36 different templates in any one chaining
  4695. operations.  You MAY use the same template more than once in the same
  4696. chain, like the following:
  4697.  
  4698.      [0370]HELLO
  4699.  
  4700. Note, that template #0 is used twice, both at the beginning and the
  4701. end of the processing.  This feature, potentially dangerous, is
  4702. provided for completeness and flexibility.
  4703.  
  4704.  
  4705. EMBEDDED TEMPLATES
  4706. ------------------
  4707. You can embed the contents of one template into another template (or
  4708. into a Host Command) by using the special Text Variable $?x$ where
  4709. "x" is the Template number to insert.  This command functions much
  4710. like the insert-text variable $?$ does, but gives you a great deal
  4711. more power and flexibility.
  4712.  
  4713. If you specify to embed one template inside another, the embedded
  4714. template can contain text variables, pick-lists and other such
  4715. things.  It can even have another embedded template in it as well,
  4716. but that sub-embedded template cannot have ANY text variables, or any
  4717. special commands, not even control characters!
  4718.  
  4719. To sum it up, an embedded template can have anything you want in it,
  4720. including other embedded templates.  All text variables in an
  4721. embedded template are expanded, as are pick lists, control characters
  4722. and the like.  If you have an embedded template INSIDE an embedded
  4723. template, the deepest embedded template will have NO text variable
  4724. processing done on it (i.e., the text is sent to the host verbatim,
  4725. exactly as it appears in the template).
  4726.  
  4727. If a template that is referenced is not yet defined, the template
  4728. embed command will be skipped (i.e., blank) providing that the
  4729. embedded template doesn't refer to a Radio Group. Radio Groups are
  4730. "dependencies" in this manner.  Anything that tries to embed a
  4731. Template from a Radio Group will not be processed if a template in
  4732. that area hasn't been defined yet.  Embedded templates from Check Box
  4733. Groups can be skipped if none of the check-boxes are active.
  4734.  
  4735.  
  4736. LISTS, VARIABLES AND CONTROL CHARACTERS
  4737. ---------------------------------------
  4738. You may use Text Variables, Pop-Up Pick Lists and Control Characters
  4739. anywhere in any template definition or reference.  You are limited
  4740. such that, a text variable is translated to its real value when the
  4741. template is being processed, not after all templates are processed.
  4742. The net result of this is, you cannot use one template to construct
  4743. another template's pick- list, text variables, or the such.
  4744.  
  4745. In other words, you cannot nest Text Variable definitions, Pop-Up
  4746. Pick Lists , or Control Characters.  You can have these commands in
  4747. any or all templates used in a template chain, but they are
  4748. independent.
  4749.  
  4750.  
  4751. TEMPLATE CHAIN EXAMPLES
  4752. -----------------------
  4753. Below are several examples of different template setups. These are
  4754. intended to give you ideas on how templates may be used:
  4755.  
  4756.   Example #1:
  4757.  
  4758.      [0:]D $?$ Z^m     ... Used to download a file with Zmodem
  4759.      [1:]D $?$ X^m     ... Used to download a file with Xmodem
  4760.  
  4761.      [0]FILENAME.ZIP   ... Use this with #0 to download Zmodem
  4762.      [1]FILENAME.ZIP   ... Use this with #1 to download Xmodem
  4763.  
  4764. In this example, template #0 is used for downloading with Zmodem.
  4765. Template #1 is for downloading with Xmodem.  Depending on which
  4766. FILENAME.ZIP button you click on, you might download it with one
  4767. protocol or with another.  It all lies on which template you
  4768. reference.  The text transmitted to the host if you clicked on the
  4769. buttons could be either:
  4770.  
  4771.      D FILENAME.ZIP Z^m
  4772.  
  4773.           - or -
  4774.  
  4775.      D FILENAME.ZIP X^m
  4776.  
  4777.  
  4778.   Example #2:
  4779.  
  4780.      D $?2$ $?1$^m    ... Make this the "Download Now" button
  4781.  
  4782.      [1:]X            ... Radio Button #1   (X-Modem)
  4783.      [1:]Y            ... Radio Button #2   (Y-Modem)
  4784.      [1:]B            ... Radio Button #3   (Y-Modem Batch)
  4785.      [1:]Z            ... Radio Button #4   (Z-Modem)
  4786.  
  4787.      [2:]FILENUM1.ZIP ... Radio Button to download file #1
  4788.      [2:]FILENUM2.ZIP ... Radio Button to download file #2
  4789.      [2:]FILENUM3.ZIP ... Radio Button to download file #3
  4790.  
  4791. This example is a bit more involved.  It brings the concept of Radio
  4792. Buttons into the picture, which is part of the Button command. A Radio
  4793. Button is like having a list of options on your screen, only one of which
  4794. can be selected at any
  4795. one time.  When using    ╔══════════════════════════════════════════════╗
  4796. templates with Radio     ║   Protocols            Download which file?  ║
  4797. Buttons, you can quickly ║   ─────────            ────────────────────  ║
  4798. and elegantly define a   ║   X X-Modem             ■ File #1            ║
  4799. menu that can do one     ║   ■ Y-Modem             X File #2            ║
  4800. thing in one mode, or    ║   ■ Y-Modem Batch       ■ File #3            ║
  4801. something totally        ║   ■ Z-Modem                                  ║
  4802. different in another     ║ ┌──────────────────────────────────────────┐ ║
  4803. mode.  An example of     ║ │           Begin Download Now!            │ ║
  4804. the above menu might be  ║ └──────────────────────────────────────────┘ ║
  4805. as follows:              ╚══════════════════════════════════════════════╝
  4806.  
  4807. In the preceding example #2, a group of Radio Buttons were used on the
  4808. right side of the screen to determine which file should be downloaded.
  4809. In that example, there was no ability to specify an arbitrary filename to
  4810. download.  You were only allowed to download one of three given files.
  4811. What would be perfect, would be to have the ability to pop-up a question
  4812. to the user asking what filename they wanted.  The solution is easy,
  4813. insert a text-variable that hasn't been defined yet!  To illustrate, the
  4814. above example could be modified to accommodate this as follows:
  4815.  
  4816.      D $?2$ $?1$^m    ... Make this the "Download Now" button
  4817.  
  4818.      [1:]X            ... Radio Button #1   (X-Modem)
  4819.      [1:]Y            ... Radio Button #2   (Y-Modem)
  4820.      [1:]B            ... Radio Button #3   (Y-Modem Batch)
  4821.      [1:]Z            ... Radio Button #4   (Z-Modem)
  4822.  
  4823.      [2:]FILENUM1.ZIP ... Radio Button to download file #1
  4824.      [2:]FILENUM2.ZIP ... Radio Button to download file #2
  4825.      [2:]FILENUM3.ZIP ... Radio Button to download file #3
  4826.      [2:]$FILENAME$   ... Radio Button to download ANY file
  4827.  
  4828. The screen might appear something like this:
  4829.  
  4830.         ╔══════════════════════════════════════════════╗
  4831.         ║   Protocols            Download which file?  ║
  4832.         ║   ─────────            ────────────────────  ║
  4833.         ║   X X-Modem             ■ File #1            ║
  4834.         ║   ■ Y-Modem             X File #2            ║
  4835.         ║   ■ Y-Modem Batch       ■ File #3            ║
  4836.         ║   ■ Z-Modem         ┌──────────────────────┐ ║
  4837.         ║                     │    Enter Filename    │ ║
  4838.         ║                     └──────────────────────┘ ║
  4839.         ║ ┌──────────────────────────────────────────┐ ║
  4840.         ║ │           Begin Download Now!            │ ║
  4841.         ║ └──────────────────────────────────────────┘ ║
  4842.         ╚══════════════════════════════════════════════╝
  4843.  
  4844. NOTE:  To get the radio button graphic show above, an Icon Button
  4845.        must be used.  The empty circle is an icon, and the filled
  4846.        in circle is a hot icon.  Refer to Section 5.3.7.
  4847.  
  4848. Note the addition of the Enter Filename button.  If the user clicked
  4849. on that button, it would first try to replace $FILENAME$ with a text
  4850. variable.  It will find that such a variable does not exist, and will
  4851. then pop-up the following question on the screen:
  4852.  
  4853.        ╔══════════════════════════════════════════════════╗
  4854.        ║                 Enter "FILENAME"                 ║
  4855.        ║ ┌──────────────────────────────────────────────┐ ║
  4856.        ║ │ █                                            │ ║
  4857.        ║ └──────────────────────────────────────────────┘ ║
  4858.        ╚══════════════════════════════════════════════════╝
  4859.  
  4860. If the user typed in DEMOFILE.TXT, then that filename is inserted
  4861. where $FILENAME$ was, resulting in (for example):
  4862.  
  4863.      D DEMOFILE.TXT Z^m
  4864.  
  4865. This is only an example, your mileage may vary.
  4866.  
  4867.  
  4868. MORE ABOUT TEMPLATES
  4869. --------------------
  4870. When you use the $?$ text variable inside a template definition, you
  4871. are not limited to using it only once.  In fact, you can use it as
  4872. many times in your template definition as you wish.  This can be
  4873. useful under many circumstances where the user might have to enter
  4874. the same thing twice.
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880. =====================================================================
  4881. ==                TEXT VARIABLE CREATION, AND QUERY                ==
  4882. =====================================================================
  4883.  
  4884. As mentioned in preceding sections, Text Variables were described as
  4885. either pre-defined variables, or as User Variables.  Pre-defined
  4886. variables are variables that RIPscrip products know things about "out
  4887. of the box".  They will always know what the variables mean, from the
  4888. day you install the software.  User Variables are variables that the
  4889. user of RIPscrip products defines, and teach it new things it doesn't
  4890. already know.
  4891.  
  4892.  
  4893. WHAT ARE USER VARIABLES?
  4894. ------------------------
  4895. A User Variable is a Text Variable that RIPscrip doesn't know exists.
  4896. They are custom-defined text variables that contain information that
  4897. the terminal user will fill in.  If a variable already contains
  4898. information, a host will be automatically told (if told to do so)
  4899. what that variable contains without the user having to intervene
  4900. (i.e., transparent information exchange).
  4901.  
  4902. Examples of Text Variables might be:
  4903.  
  4904.      $FULL_NAME$    ... What is your full name?
  4905.      $COMPANY_NAME$ ... What company do you work for?
  4906.      $AGE$          ... How old are you?
  4907.      $DATEOFBIRTH$  ... What is your Date of Birth?
  4908.      $PHONENUMBER$  ... What is your Day-time phone number?
  4909.  
  4910. User Variables will "keep track" of these responses for you, in the
  4911. terminal program database.  You can tell the terminal to store these
  4912. values permanently, or they may be active only during the current
  4913. session, or they may be defined as temporary where they are not
  4914. stored for more than a brief moment.
  4915.  
  4916. NOTE:  This ability is configurable so that information exchange
  4917.        can be either interactive, or automatic.  Automatic
  4918.        transfer of information does NOT prompt the user with the
  4919.        information unless the variable has not yet been defined.
  4920.        If it has not been defined, a pop-up question will appear
  4921.        asking the user a particular question, thus defining the
  4922.        text variable.
  4923.  
  4924. If the exchange is interactive, the data is displayed in a pop-up
  4925. editor box, asking you if the information is correct.  If it is,
  4926. press ENTER and the retrieved information is sent to the host for
  4927. you.  If it is not correct, or it has not been created yet, just type
  4928. it in and press ENTER and it will be saved automatically, and sent to
  4929. the host all at once.
  4930.  
  4931.  
  4932. HOW CAN USER VARIABLES BE IMPORTANT?
  4933. ------------------------------------
  4934. Lets take an example.  You are the system operator of a large
  4935. RIPscrip host.  As you have read, RIPscrip can take advantage of
  4936. database-like ability on the terminal end.  If you can alter your
  4937. host to ask questions with RIPscrip Text Variables built in, you can
  4938. have the terminal calling your host automatically fill in
  4939. questionnaires.  Imagine if a user could sign-up on your host without
  4940. having to type more than a single keystroke (i.e., "YES, this
  4941. information is correct").  With User Text Variables, you can do this
  4942. very thing.
  4943.  
  4944.  
  4945. CREATING USER VARIABLES
  4946. -----------------------
  4947. There are two ways of defining User Text Variables in RIPaint.  You
  4948. can use either the Define Text Variable command, or you can use Text
  4949. Variable Queries, as described in the next section.
  4950.  
  4951.  
  4952. DEFINING TEXT VARIABLES
  4953. -----------------------
  4954. The RIPscrip command Define Text Variable is by definition, an
  4955. interactive command with the user.  The RIPscrip command will attempt
  4956. to define a User Variable.  This variable is some piece of
  4957. information that the system operator deems important.  You may
  4958. specify a question, a default response, and how many characters long
  4959. the response may be.
  4960.  
  4961. Once the terminal has received a define command, the terminal pops up
  4962. an appropriate question box on the user's screen, asking him the
  4963. desired question that should be saved to a particular Text Variable.
  4964. If you did not specify a question, a default question is used (i.e.,
  4965. "Enter <name of text variable>").
  4966.  
  4967. Once the user has entered his response, it is recorded and saved.
  4968. How long it is stored depends on what the host told the terminal. The
  4969. host can tell the terminal "save this on your hard disk forever". The
  4970. host may also tell the terminal "don't save this to disk, but
  4971. remember this value until you exit RIPterm".  You also have the
  4972. option of saying "don't remember this value at all, just pop up a
  4973. question, and send the value to me NOW" - i.e., don't save it at all,
  4974. just enter it and send it to the host).
  4975.  
  4976.  
  4977. QUERYING TEXT VARIABLES
  4978. -----------------------
  4979. Now that you know how to define information on the terminal, you need
  4980. to know the last method of asking the terminal about text variables.
  4981. This feature is called "Data Query".
  4982.  
  4983. Data Query is a generic query command that can ask the terminal one
  4984. or more questions, and tell it how to transmit the information back
  4985. to the host.  This command is for use in non-button situations where
  4986. you do not want to wait until the user clicks on a button to get your
  4987. data back.
  4988.  
  4989. Data Query is a special RIPscrip command that can be used to ask the
  4990. contents of one or more Text Variables.
  4991.  
  4992.  
  4993. EXAMPLES OF TEXT VARIABLE QUERY
  4994. -------------------------------
  4995. Lets take a simple example.  You wanted to ask the terminal program
  4996. some address information.  You could do this with the following query
  4997. (remember, the query also tells the terminal HOW to send the data back
  4998. to the host):
  4999.  
  5000.      $FULL_NAME$^m$COMPANY$^m$ST_ADDR$^m$CITY$, $STATE$ $ZIP^m
  5001.  
  5002. This would query the terminal the contents of 6 text variables, and
  5003. format them in a manner similar to any normal address on an envelope.
  5004. The results of this query might send the following back to the host :
  5005.  
  5006.      Joe Sixpack
  5007.      ACME Corporation
  5008.      13631 Palindrome Parkway
  5009.      Surf City, CA 92649
  5010.  
  5011. If a text variable is queried, and it has not been defined yet, a
  5012. pop-up question will appear asking the user to fill in the
  5013. information.
  5014.  
  5015.  
  5016.  
  5017. ===================================================================== > v1.54
  5018. ==            RIPscrip ICON FILE FORMAT SPECIFICATION             === > v1.54
  5019. ===================================================================== > v1.54
  5020.                                                                       > v1.54
  5021. The following section describes the exact file format specification   > v1.54
  5022. of the RIPscrip Icon File.  It is identical in design to the Borland  > v1.54
  5023. BGI graphics putimage() and getimage() buffer format.                 > v1.54
  5024.                                                                       > v1.54
  5025. The beginning of the file contains a header structure at file offset  > v1.54
  5026. zero.  It is exactly four bytes in length.  Here is the "C" structure > v1.54
  5027. definition for this header:                                           > v1.54
  5028.                                                                       > v1.54
  5029.    struct iconfile_header {                                           > v1.54
  5030.           int width;        /* Width  of image in pixels (minus 1) */ > v1.54
  5031.           int height;       /* Height of image in lines  (minus 1) */ > v1.54
  5032.    };                                                                 > v1.54
  5033.                                                                       > v1.54
  5034. After the header follows each scan-line of the bitmap.  Each          > v1.54
  5035. scan-line is segmented into four chunks in 16-color mode.  In 256     > v1.54
  5036. color mode it is segmented into 8 chunks.  All chunks of the          > v1.54
  5037. scan-line are monochrome bitmaps of a horizontal line.  Each chunk    > v1.54
  5038. is padded to an even 8-pixels (bytes).  Each of the scan-line         > v1.54
  5039. chunks are merged together to create one full-scan-line bitmap.       > v1.54
  5040.                                                                       > v1.54
  5041. After the first scan-line's segments follows the next scan-line's     > v1.54
  5042. four segments (or 8), and so on.  After all the scan-lines is 1-byte  > v1.54
  5043. of "trash" data which is never used and its value is undefined (who   > v1.54
  5044. knows why?)...                                                        > v1.54
  5045.                                                                       > v1.54
  5046. The general format of an iconfile buffer is:                          > v1.54
  5047.      _______________________________                                  > v1.54
  5048.     |                               |                                 > v1.54
  5049.     |            HEADER             |  4 bytes                        > v1.54
  5050.     |_______________________________|                                 > v1.54
  5051.     |                               |                                 > v1.54
  5052.     |  Scan line #1 (bit plane 3)   |                                 > v1.54
  5053.     |  Scan line #1 (bit plane 2)   |                                 > v1.54
  5054.     |  Scan line #1 (bit plane 1)   |                                 > v1.54
  5055.     |  Scan line #1 (bit plane 0)   |                                 > v1.54
  5056.     |_______________________________|                                 > v1.54
  5057.     |                               |                                 > v1.54
  5058.     |  Scan line #2 (bit plane 3)   |                                 > v1.54
  5059.     |  Scan line #2 (bit plane 2)   |                                 > v1.54
  5060.     |  Scan line #2 (bit plane 1)   |                                 > v1.54
  5061.     |  Scan line #2 (bit plane 0)   |                                 > v1.54
  5062.     |_______________________________|                                 > v1.54
  5063.     |                               |                                 > v1.54
  5064.     |  Scan line #n (bit plane 3)   |                                 > v1.54
  5065.     |  Scan line #n (bit plane 2)   |                                 > v1.54
  5066.     |  Scan line #n (bit plane 1)   |                                 > v1.54
  5067.     |  Scan line #n (bit plane 0)   |                                 > v1.54
  5068.     |_______________________________|                                 > v1.54
  5069.     |                               |                                 > v1.54
  5070.     |           TRASH BYTE          |   1 byte                        > v1.54
  5071.     |_______________________________|                                 > v1.54
  5072.                                                                       > v1.54
  5073.                                                                       > v1.54
  5074. Example:                                                              > v1.54
  5075.                                                                       > v1.54
  5076. If you had a bitmap image (2 scan lines high) containing the          > v1.54
  5077. following pixel colors:                                               > v1.54
  5078.                                                                       > v1.54
  5079.                     < X pos >                                         > v1.54
  5080.                 0  1  2  3  4  5                                      > v1.54
  5081.               -------------------                                     > v1.54
  5082.      <Y>   0 | 00 01 02 04 08 0F                                      > v1.54
  5083.            1 | 03 05 08 03 02 01                                      > v1.54
  5084.                                                                       > v1.54
  5085. IN BINARY:                                                            > v1.54
  5086.                                                                       > v1.54
  5087.      0000 0001 0010 0100 1000 1111                                    > v1.54
  5088.      0011 0101 1000 0011 0010 0001                                    > v1.54
  5089.      ||| \                                                            > v1.54
  5090.      || \ \                                                           > v1.54
  5091.      | \ \ \                                                          > v1.54
  5092.       \ \ \ \ Bit plane #0                                            > v1.54
  5093.        \ \ \                                                          > v1.54
  5094.         \ \ \ Bit plane #1                                            > v1.54
  5095.          \ \                                                          > v1.54
  5096.           \ \ Bit plane #2                                            > v1.54
  5097.            \                                                          > v1.54
  5098.             \ Bit plane #3                                            > v1.54
  5099.                                                                       > v1.54
  5100. Breaking this up into bit-planes, you have the following four         > v1.54
  5101. monochrome patterns (in reverse order):                               > v1.54
  5102.                                                                       > v1.54
  5103.      000011    Bit plane #3   (bit #3 in each pixel)                  > v1.54
  5104.      001000                                                           > v1.54
  5105.                                                                       > v1.54
  5106.      000101    Bit plane #2   (bit #2 in each pixel)                  > v1.54
  5107.      010000                                                           > v1.54
  5108.                                                                       > v1.54
  5109.      001001    Bit plane #1   (bit #1 in each pixel)                  > v1.54
  5110.      100110                                                           > v1.54
  5111.                                                                       > v1.54
  5112.      010001    Bit plane #0   (bit #0 in each pixel)                  > v1.54
  5113.      110101                                                           > v1.54
  5114.                                                                       > v1.54
  5115. Since these bit patterns are not an even byte in size, pad remaining  > v1.54
  5116. bits on the right with 0 bits (these are "don't care bits"):          > v1.54
  5117.                                                                       > v1.54
  5118.             vv--- don't care bits                                     > v1.54
  5119.    A: 00001100 = 0Ch - Bit plane #3               WIDTH  = 6 pixels   > v1.54
  5120.    B: 00100000 = 20h                              HEIGHT = 2 lines    > v1.54
  5121.                                                                       > v1.54
  5122.    C: 00010100 = 14h - Bit plane #2                                   > v1.54
  5123.    D: 01000000 = 40h                                                  > v1.54
  5124.                                                                       > v1.54
  5125.    E: 00100100 = 24h - Bit plane #1                                   > v1.54
  5126.    F: 10011000 = 98h                                                  > v1.54
  5127.                                                                       > v1.54
  5128.    G: 01000100 = 44h - Bit plane #0                                   > v1.54
  5129.    H: 11010100 = C4h                                                  > v1.54
  5130.                                                                       > v1.54
  5131.                                                                       > v1.54
  5132. The final structure of the entire iconfile buffer would be as follows > v1.54
  5133. in this example:                                                      > v1.54
  5134.                                                                       > v1.54
  5135.    Offset  VALUE             Ref    Description                       > v1.54
  5136.    ==============================================================     > v1.54
  5137.      00:   05 00          /* ---    Width  6-1=5               */     > v1.54
  5138.      02:   01 00          /* ---    Height 2-1=1               */     > v1.54
  5139.      04:   0C             /* (A)    Scan line #0, bit plane #3 */     > v1.54
  5140.      05:   14             /* (C)    Scan line #0, bit plane #2 */     > v1.54
  5141.      06:   24             /* (E)    Scan line #0, bit plane #1 */     > v1.54
  5142.      07:   44             /* (G)    Scan line #0, bit plane #0 */     > v1.54
  5143.                                                                       > v1.54
  5144.      08:   20             /* (B)    Scan line #1, bit plane #3 */     > v1.54
  5145.      09:   40             /* (D)    Scan line #1, bit plane #2 */     > v1.54
  5146.      0A:   98             /* (F)    Scan line #1, bit plane #1 */     > v1.54
  5147.      0B:   C4             /* (H)    Scan line #1, bit plane #0 */     > v1.54
  5148.                                                                       > v1.54
  5149.      0C:   00             /* ---    TRASH BYTE - UNKNOWN VALUE */     > v1.54
  5150.  
  5151.  
  5152.  
  5153. WHAT IS A TEMPLATE?
  5154. -------------------
  5155. A template is a special variety of a host command that is used to
  5156. construct other host commands.  They are only used with the
  5157. RIP_BUTTON command, not with RIP_MOUSE or RIP_QUERY.  Their use is
  5158. solely dedicated to the Button command.  In fact, their usefulness is
  5159. predominantly designed for Radio Buttons and Check Box Buttons but
  5160. this doesn't mean that you cannot use them for other purposes.
  5161.  
  5162. A template, like a normal "raw" Host Command, is stored in the Host
  5163. Command field of the RIP_BUTTON command.  Unlike Raw Host Commands
  5164. that get sent to the Host immediately, templates do not transmit
  5165. immediately.  In fact, it's possible for a Template to never get
  5166. transmitted to the BBS at all.  Templates are not normally sent
  5167. directly to the BBS - they are almost always used in conjunction with
  5168. some other button's host command.
  5169.  
  5170.  
  5171.  
  5172. HOST COMMANDS - ADDING ANOTHER WRINKLE
  5173. --------------------------------------
  5174. As you know with normal Mouse Host Commands, you can send any piece
  5175. of text you want when the user clicks on that button.  You could send
  5176. the word "HELLO" to the BBS for example if they click on a certain
  5177. mouse button.  This is an example of a "Direct Host Command".
  5178.  
  5179. There are three types of Host Commands.  There are:
  5180.  
  5181.      1) DIRECT HOST COMMANDS - Send a string of text to the host
  5182.         immediately after the associated button is clicked.
  5183.  
  5184.      2) TEMPLATE DEFINITIONS - Defines a template to be used by
  5185.         other buttons (if ever).  See below for further details
  5186.         about how to define templates.
  5187.  
  5188.      3) TEMPLATE EXECUTION - This allows you to plug a piece of
  5189.         string data into one or more templates (defined previously).
  5190.         The resulting string is then acted upon like a Direct Host
  5191.         Command and transmitted to the BBS immediately.
  5192.  
  5193. The RIP_BUTTON command "segments" its Text Parameter Block into three
  5194. portions - the Icon File, Text Label followed by the Host Command
  5195. block.  Each of these segments is separated by the two character
  5196. delimiter "<>" like this:
  5197.  
  5198.           ICONFILE.ICN<>Button Label<>HOST COMMAND.
  5199.  
  5200. With the Button command, the Host Command segment can be sub-divided
  5201. into numerous smaller sub-segments, or Command Blocks.  This is done
  5202. with another two character delimiter "[]".  So, technically, you could
  5203. do this:
  5204.  
  5205.      ICONFILE.ICN<>Button Label<>HELLO^m[]WORLD^m
  5206.  
  5207. This command would show an Icon Button using the file ICONFILE.ICN as
  5208. its Icon Image, labeling it with the phrase "Button Label", and
  5209. defining an extended Host Command block with two segments.  If the user
  5210. clicks on this button, the following will be sent to the BBS:
  5211.  
  5212.      HELLO<cr>
  5213.      WORLD<cr>
  5214.  
  5215. Notice how the "[]" is not transmitted.  This is because it is simply
  5216. a delimiter separating two Command Blocks from each other.  Now each
  5217. of these two command blocks are DIRECT HOST COMMANDS, but they don't
  5218. have to be.  One of them could have been a Direct Host Command, and
  5219. another could just as easily have been a template definition.
  5220.  
  5221.  
  5222.  
  5223. TIPTOE THROUGH THE TEMPLATES
  5224. ----------------------------
  5225. There can be up to 36 different templates defined simultaneously. 
  5226. Each template number corresponds directly to a Button Group Number.
  5227. Templates are identified by a single meganum 0-9 and A-Z, leaving 36
  5228. distinctly separate groups.  To define a template, you use a
  5229. variation of the Command Block delimiter "[]" with the template
  5230. identifier followed by a colon like this:
  5231.  
  5232.      [5:]This is template #6's definition
  5233.      [G:]This is template #16's definition
  5234.  
  5235. Defining a template is simple.  Activating a template however, is
  5236. another story.  What if three buttons in the same group all define
  5237. their own templates for the same group/template like this:
  5238.  
  5239.      Button #1:   [5:]This is button #1's template
  5240.      Button #2:   [5:]This is button #2's template
  5241.      Button #3:   [5:]This is button #3's template
  5242.  
  5243. Now, when these three buttons are received by the terminal, it 
  5244. [the terminal] knows the Host Commands for each button (it memorized
  5245. each of them).  Now, which of these three templates is the currently
  5246. active one?  None of them!  A template definition doesn't become the
  5247. active template until that button containing its definition is
  5248. clicked (selected).  What this means is, you can have a bunch of
  5249. buttons all belonging to the same Button Group with their own
  5250. respective template definitions, but only the template relating to
  5251. the most recently clicked button will be the currently active
  5252. template for that group.  Whew, that was a mouthful!
  5253.  
  5254. There are two ways of activating a template:
  5255.  
  5256.      1) Draw a button as "pre-selected" - in other words, the
  5257.         button is drawn pre-clicked immediately when it is
  5258.         received by the terminal.  When this happens, the
  5259.         Host Command for that button is processed immediately
  5260.         and if a template definition exists in that host command,
  5261.         it is acted upon immediately thus making that template
  5262.         the currently active template for that Group.
  5263.  
  5264.      2) The user clicks on a button containing a template
  5265.         definition.  If a template is already active in that
  5266.         group, it is overwritten by the newly activated template.
  5267.  
  5268. In either case when templates are defined, nothing is actually
  5269. transmitted to the BBS unless the Command Block contains some Direct
  5270. Host Command sub-block(s) like this:
  5271.  
  5272.      [5:]Template definition[]hello world^m
  5273.  
  5274. If this button were clicked, then Group number 5 would have the
  5275. template activated with the template text "Template definition". 
  5276. Then the Direct Host Command "hello world^m" would be transmitted to
  5277. the BBS.  In this example, we see how a single host command can do
  5278. multiple things - in this case, it defined a template in group #5 AND
  5279. transmitted something to the BBS!
  5280.  
  5281.  
  5282.  
  5283. TEMPLATES, RADIO BUTTONS AND CHECK-BOX BUTTONS
  5284. ----------------------------------------------
  5285. We have seen how templates are defined and activated.  Before we go
  5286. any further, let's explain how they are used for Radio Buttons and
  5287. Check-Box buttons.
  5288.  
  5289. Radio Buttons are a "type" of button group.  Only one button in that
  5290. group can be active (clicked) at any one time.  If a button that is
  5291. not active is clicked, any other buttons in that group that ARE
  5292. clicked are de-selected and the one that is being clicked is
  5293. selected.  If that newly clicked button has a Host Command, it is
  5294. processed.  If it has a template definition, it too is processed,
  5295. overwriting the currently defined template for the specified group.
  5296. Since Radio Buttons can only have one currently active button in a
  5297. single given Radio Group, similarly you can only have one template
  5298. active for that group at any given moment.
  5299.  
  5300. Check Box Buttons are another "type" of button group.  Unlike Radio
  5301. Buttons, Check Box buttons can have zero or more buttons active
  5302. (clicked) at any one time.  If a check box button group has ten
  5303. buttons defined in it, zero, five or all ten of those buttons can be
  5304. active simultaneously.  What about each of their respective Host
  5305. Commands?  They too are all processed when the buttons are
  5306. individually clicked.  Now what about templates?  Since you can only
  5307. have one template defined in a group at any given moment, how do
  5308. check box buttons accomplish this multiple-template concept? 
  5309. Whenever a check box button is clicked (or unclicked), the template
  5310. for that group is re-calculated.  Any buttons in that group that have
  5311. template definitions are scanned, and any check box buttons in that
  5312. group that are selected, have their template definitions concatenated
  5313. together (strung together) end on end.  The result is one large
  5314. template which is built up from the template definitions of each
  5315. selected check box button.
  5316.  
  5317. Let's take a couple simple examples step-by-step to see how templates
  5318. are maintained internally.  In the first example, we will explore the
  5319. Radio Buttons and the way templates relate to them.  In the second
  5320. example, we'll examine check box buttons and templates.
  5321.  
  5322.  
  5323.  
  5324. EXAMPLE 1 - RADIO BUTTON TEMPLATES
  5325. ----------------------------------
  5326. Let's say you have four buttons in Button Group #3, and that button
  5327. group is defined as a Radio Button group.  Here are the host command
  5328. definitions for each of those buttons in this example:
  5329.  
  5330.      Button #1:   [3:]ABCD
  5331.      Button #2:   [3:]EFGH
  5332.      Button #3:   [3:]IJKL
  5333.      Button #4:   [3:]MNOP
  5334.  
  5335. Now, if none of the buttons are clicked, then template group #3 is
  5336. blank.  If button #1 is clicked, the template for group #3 would be
  5337. defined as "ABCD".  Now, if button #4 is clicked, what would the
  5338. template definition for group #3 be?  That's right, "MNOP".  Notice
  5339. how only one of the given templates is active at any given moment.
  5340.  
  5341.  
  5342.  
  5343. EXAMPLE 2 - CHECK BOX TEMPLATES
  5344. -------------------------------
  5345. Now let's explore the slightly more complex world of check box
  5346. templates.  As stated previously, check box templates can be strung
  5347. along together to make a larger template - template construction of
  5348. sorts.  Let's say you have a Button Group #2 defined as a check box
  5349. group with 7 buttons defined in it.  Each of the buttons are
  5350. initially drawn as "unselected", or unclicked (inactive).  Here are
  5351. the button host command definitions for each of the 7 buttons:
  5352.  
  5353.      Button #1:   [2:]Apples^m
  5354.      Button #2:   [2:]Oranges^m
  5355.      Button #3:   [2:]Cherries^m
  5356.      Button #4:   [2:]Grapes^m
  5357.      Button #5:   [2:]Pears^m
  5358.      Button #6:   [2:]Banannas^m
  5359.      Button #7:   [2:]Lemons^m
  5360.  
  5361. Now, if all 7 buttons are not clicked, then template group #2 would
  5362. be blank.  Let's click on some buttons and see what the template will
  5363. become as we change which buttons are clicked and which aren't:
  5364.  
  5365.      Button #3 clicked (ON) .... Template:  Cherries^m
  5366.      Button #5 clicked (ON) .... Template:  Cherries^mPears^m
  5367.      Button #3 clicked (OFF) ... Template:  Pears^m
  5368.      Button #5 clicked (OFF) ... Template:  <blank>
  5369.      Button #2 clicked (ON) .... Template:  Oranges^m
  5370.      Button #1 clicked (ON) .... Template:  Apples^mOranges^m
  5371.      Button #4 clicked (ON) .... Template:  Apples^mOranges^mGrapes^m
  5372.  
  5373. As you can see, the active template for a check box group is actually
  5374. a combination of all selected buttons' templates, in ORDER OF
  5375. DEFINITION, not in the order that they were clicked.  Pay close
  5376. attention to the end of the example where buttons were clicked in the
  5377. order of 2, 1 then 4.  If you notice the active template though, they
  5378. are in 1, 2 then 4 order!  They are in the order that the buttons
  5379. were originally defined.
  5380.  
  5381.  
  5382.  
  5383. TAKING ADVANTAGE OF TEMPLATES
  5384. -----------------------------
  5385. We've already gone through and shown you how to define templates and
  5386. how to activate them.  Now you need to know how to put them to use -
  5387. how to take a template and make it do something.  If you've been
  5388. confused up to this point, don't worry - we're going to put it all
  5389. together in a few minutes into one big picture.
  5390.  
  5391. There are two ways of using templates.  One is called Template
  5392. Chaining, and another is called Template Embedding.  Each of these
  5393. two methods are quite different, but give you quite a bit of
  5394. flexibility.  Let's take each of these methods step-by-step by
  5395. describing each in detail separately.
  5396.  
  5397.  
  5398.  
  5399. TEMPLATE EMBEDDING
  5400. ------------------
  5401. Template embedding is a way of "inserting" a template inside another
  5402. host command.  What this means is that you can insert the contents of
  5403. an active template inside of a button's Direct Host Command.  The
  5404. direct host command is "expanded" around the inserted template and
  5405. the contents of the specified template are made part of the direct
  5406. host command.
  5407.  
  5408. Let's illustrate this with an example.  Taking the check box example
  5409. above which had a list of fruits as check box buttons, we can expand
  5410. on this example to show how template embedding can be a useful tool. 
  5411. In this example, we will build a menu to take someone's order for
  5412. fruit.  Here is what the simple menu screen will look like:
  5413.  
  5414.       +----------------------------------------+
  5415.       |     What would you like to order?      |
  5416.       |                                        |
  5417.       | +-----------+                          |
  5418.       | |X  Apples  |                          |
  5419.       | |   Oranges |         +------------+   |
  5420.       | |X  Cherries|         |Submit order|   |
  5421.       | |   Grapes  |         +------------+   |
  5422.       | |X  Pears   |                          |
  5423.       | |   Banannas|                          |
  5424.       | |X  Lemons  |                          |
  5425.       | +-----------+                          |
  5426.       +----------------------------------------+
  5427.  
  5428. As you can see, we have a set of 7 check box buttons on the left of
  5429. the menu with the choices of the fruits for sale.  On the right is a
  5430. button to submit your order.  To implement this example, we will use
  5431. two separate button groups.  Group #0 will contain one button, the
  5432. "Submit Order" button.  Button Group #2 will be a check box button
  5433. group containing our seven choices of fruits as in the preceding
  5434. example.  Here are the Host Command definitions for each of the eight
  5435. buttons:
  5436.  
  5437.      Group #0 (normal button - not a radio or check-box button)
  5438.      ----------------------------------------------------------
  5439.           SUBMIT ORDER:   I wish to order $?2$ right now^m
  5440.  
  5441.      Group #2 (check box button group)
  5442.      ---------------------------------
  5443.           APPLES:    [2:]APPLES^m
  5444.           ORANGES:   [2:]ORANGES^m 
  5445.           CHERRIES:  [2:]CHERRIES^m
  5446.           GRAPES:    [2:]GRAPES^m  
  5447.           PEARS:     [2:]PEARS^m   
  5448.           BANANNAS:  [2:]BANANNAS^m
  5449.           LEMONS:    [2:]LEMONS^m
  5450.   
  5451. Notice in the "Submit Order" button that there is a special code in
  5452. the Direct Host Command "$?2$".  This is a special variation of a text
  5453. variable.  This form of text variable is used only in Template
  5454. Embedding.  What it does is instructs the terminal to "insert template
  5455. #2 here".  The format of the template embedding code is:
  5456.  
  5457.           $?x$
  5458.  
  5459. ...where "x" is the template identifier (0-Z) that is to be inserted.
  5460. Now back to the example, if the user clicked on "APPLES", "CHERRIES",
  5461. "PEARS" and "LEMONS" as in the menu shown above, then clicks on
  5462. "Submit Order", what would the Host Command look like when it gets
  5463. transmitted to the BBS?  Well, for starters, the Submit Order
  5464. button's host command reads:
  5465.  
  5466.      I wish to order $?2$ right now^m
  5467.  
  5468. After template #2 is inserted where the embedding code is, the host
  5469. command would look like this:
  5470.  
  5471.      I wish to order APPLES^mCHERRIES^mPEARS^mLEMONS^m right now^m
  5472.  
  5473. And after the ^m's are converted to carriage returns the final host
  5474. command would be like this:
  5475.  
  5476.      I wish to order APPLES
  5477.      CHERRIES
  5478.      PEARS
  5479.      LEMONS
  5480.      right now
  5481.  
  5482. What if the user didn't click on any of the fruits, but did click on
  5483. the Submit Order button?  Well, since template #2 belongs to a group
  5484. that is a Check Box group, which can have zero or more items selected
  5485. simultaneously, the $?2$ code would be expanded to a null string, or
  5486. nothing, so the final host command would be:
  5487.  
  5488.      I wish to order  right now
  5489.  
  5490. If template #2 was associated with a Radio group which has to have
  5491. one button clicked at all times, and none of the buttons were active,
  5492. then the terminal would hilight all the radio buttons in group #2 and
  5493. instruct the user to choose one first.  This is done automatically by
  5494. the terminal, you don't need to worry about Radio Buttons.
  5495.  
  5496. Just remember, Check Box buttons can legitimately have a blank
  5497. template, but Radio Buttons cannot due to the very nature of the
  5498. buttons.
  5499.  
  5500. The final host command after template embedding is limited to 4096
  5501. bytes of data.  If a host command would grow beyond 4096 bytes due to
  5502. embedding, it is truncated to exactly 4096 bytes.
  5503.  
  5504.  
  5505.  
  5506. TEMPLATE CHAINING
  5507. -----------------
  5508. Now, on to the second form of using templates, Template Chaining. 
  5509. Template Chaining is another method of using templates.  Unlike
  5510. Template Embedding though, template chaining is quite different. 
  5511. Rather than inserting the contents of a template into a host command,
  5512. like in embedding, template chaining feeds data into a template and
  5513. then takes the result and transmits that to the BBS.  In other words,
  5514. Template Embedding inserts a template into a Host Command.  In
  5515. Template Chaining, a Host Command is inserted into a template (the
  5516. exact opposite).
  5517.  
  5518. If you recall from the Template Embedding discussion earlier, there
  5519. was a code for inserting a template into a host command.  The command
  5520. was $?x$ where "x" was the template number.  Template Chaining uses a
  5521. similar insertion code but with a subtle different - there is no
  5522. template identifier.  The code is:
  5523.  
  5524.      $?$
  5525.  
  5526. This is a "generic insertion code".  It is used in the template
  5527. definition itself, not in the Direct Host Command like the template
  5528. embedding code was used.  The actual data that replaces the $?$
  5529. depends on the Direct Host Command that is "feeding" the template.
  5530.  
  5531. Before template chaining becomes crystal clear, we need to muddy the
  5532. waters some more by introducing one more thing - the Chaining
  5533. command.  A template chaining operation is performed almost exactly
  5534. like defining a template with a subtle difference, the colon (:) is
  5535. omitted from the template definition like this:
  5536.  
  5537.      [5]This is template chaining
  5538.      [5:]This is template definition
  5539.  
  5540. What's the difference?  In the case of the [5:], a template for group
  5541. #5 is defined.  In the [5] example, the template chaining instruction
  5542. is invoked on Template #5.  The phrase "This is template chaining"
  5543. will be fed into template number 5.  If template number 5 has a
  5544. generic insertion code $?$ in it, then it will be replaced with the
  5545. phrase "This is template chaining".  The final result after the
  5546. replacement will be a direct host command that will be transmitted to
  5547. the BBS.  Since template #5 doesn't have an insertion code, the
  5548. phrase "This is template chaining" will be lost in the chaining
  5549. process and the final host command would be "This is template
  5550. definition".
  5551.  
  5552. Here are a couple examples of template chaining illustrating several
  5553. ways that it may be used (we'll only show "active" template
  5554. definitions):
  5555.  
  5556.      [3:]This is a plain old template
  5557.      [4:]This template inserts $?$ here!
  5558.      [5:]This has two insertion codes $?$ and $?$
  5559.  
  5560.      [3]This text is lost in the chaining process
  5561.      [4]SOMETHING
  5562.      [5]HERE
  5563.  
  5564. This would be the result of the three chaining operations:
  5565.  
  5566.      3 ... This is a plain old template
  5567.      4 ... This template inserts SOMETHING here!
  5568.      5 ... This has two insertion codes HERE and HERE
  5569.  
  5570. We skipped over the "user clicked on this button" operations and went
  5571. directly to the end results to make the example as clear as possible. 
  5572. There are three distinctly different situations in this example.  The
  5573. first shows a regular template without an insertion code being used
  5574. in a chaining operation.  As you can see, the data that was fed into
  5575. template #3 was lost because template #3 didn't have an insertion
  5576. code.  In the second example, a single insertion code is used and the
  5577. word "SOMETHING" is inserted in place of the insertion code.  The
  5578. third example shows that an insertion code can be used more than once
  5579. in a given template.
  5580.  
  5581. What if you tried to chain to a template that hasn't been activated
  5582. yet (ie, a blank template)?  If the template in question belongs to a
  5583. radio group, then the terminal would instruct the user to click on
  5584. one of the radio buttons to activate the template (he doesn't know
  5585. that templates are invovled of course).  If it was a check box
  5586. template, then the final host command would be nothing and in effect,
  5587. nothing would be transmitted to the host.  If the template in
  5588. question belonged to a generic button group, then also nothing would
  5589. get transmitted to the BBS.
  5590.  
  5591. In the preceding Template Chaining examples, only one template was
  5592. used (chained-to).  In reality, you can chain to multiple templates
  5593. with ease.  The format of multiple Template Chaining is simple, just
  5594. add the template identifiers for the templates you want to chain to
  5595. in the order you wish to chain to like this:
  5596.  
  5597.      [1E3]This is a three-level chaining operation
  5598.  
  5599. Notice how the Template Chain command has three template identifiers
  5600. in it, 1, E and 3.  The Host Command would be fed into template #1
  5601. first.  After any replacements, the final result of the template #1
  5602. chaining would be finished and that string of text would be fed into
  5603. template #E.  After any replacements/insertions are performed on
  5604. template #E, then the final result is fed into template #3 and the
  5605. final result of that chaining operation is sent to the BBS.
  5606.  
  5607. Here is an example of multiple template chaining calls:
  5608.  
  5609.      [1:]red green $?$ blue
  5610.      [E:]LOUD QUIET $?$ YELL
  5611.      [3:]soft $?$ hard smooth gritty
  5612.  
  5613.      [1E3](host command)
  5614.  
  5615. In this example, the phrase (host command) is fed into template #1,
  5616. then the result into template #E then that result into template #3
  5617. then finally transmitted to the BBS.  We can break this down
  5618. conceptually into three separate chaining operations to illustrate
  5619. what happens step-by-step:
  5620.  
  5621.      [1E3](host command)
  5622.  
  5623. Results in:
  5624.  
  5625.      [E3]red green (host command) blue
  5626.  
  5627. Resulting in:
  5628.  
  5629.      [3]LOUD QUIET red green (host command) blue YELL
  5630.  
  5631. And then finally:
  5632.  
  5633.      soft LOUD QUIET red green (host command) blue YELL hard smooth gritty
  5634.  
  5635. This last phrase is then sent to the BBS verbatim.  As you can see,
  5636. things can get pretty complex when multiple template chains are used,
  5637. however some dramatic things can be achieved with a little bit of
  5638. effort and some well thought out planning of your template
  5639. definitions.  Template chaining is useful for controlling HOW
  5640. particular data is transmitted to the BBS, while template embedding
  5641. is useful for controlling WHAT data is transmitted to the BBS.
  5642.  
  5643. You can think of template chaining as a method of defining "commands"
  5644. that will be sent to the BBS where the commands can be different
  5645. depending on which buttons are clicked in that group.  Template
  5646. embedding on the other hand is often used for controlling the data
  5647. parameters that are used with particular commands.
  5648.  
  5649. You are allowed up to 36 separate template chaining levels in one
  5650. template chaining operation.  After all chaining is completed, the
  5651. final host command cannot exceed 4096 bytes.  If a chaining operation
  5652. would exceed that amount, it is truncated to exactly 4096 bytes.
  5653.  
  5654.  
  5655.  
  5656. GETTING FANCY WITH TEMPLATES
  5657. ----------------------------
  5658. You've already learned about Template Embedding and Template
  5659. Chaining.  These two methods of using templates do not need to be
  5660. separate methods.  You can combine these methods if you wish.  This
  5661. means that you can have embedded templates inside of template chains. 
  5662. This provides for utter flexibility in doing whatever you want.
  5663.  
  5664. Here are a couple of examples of combinations:
  5665.  
  5666.    EXAMPLE 1
  5667.    ---------
  5668.  
  5669.           [5:]EMBEDDED VALUE
  5670.  
  5671.           [3:]Here is a $?$ and an $?5$
  5672.  
  5673.           [3]CHAINED HOST COMMAND
  5674.  
  5675.      This would result in:
  5676.  
  5677.           Here is a CHAINED HOST COMMAND and an EMBEDDED VALUE
  5678.  
  5679.  
  5680.    EXAMPLE 2
  5681.    ---------
  5682.  
  5683.           [5:]EMBEDDED VALUE
  5684.  
  5685.           [3:]Here is a $?$ and an $?5$
  5686.           [4:]print("$?$")
  5687.  
  5688.           [34]CHAINED HOST COMMAND
  5689.  
  5690.      This would result in:
  5691.  
  5692.           print("Here is a CHAINED HOST COMMAND and an EMBEDDED VALUE")
  5693.  
  5694.  
  5695.    EXAMPLE 3
  5696.    ---------
  5697.  
  5698.           [4:](hello)
  5699.           [5:]ANOTHER $?5$ EMBEDDED $?4$ VALUE
  5700.      
  5701.           [3:]Here is a $?$ and $?5$
  5702.  
  5703.           [3]CHAINED COMMAND
  5704.  
  5705.      This would result in:
  5706.  
  5707.           Here is a CHAINED COMMAND and ANOTHER ANOTHER $?5$ EMBEDDED $?4$
  5708.           VALUE EMBEDDED (hello) VALUE
  5709.  
  5710.      Taking this one step-by-step:
  5711.  
  5712.           Step #1:   Here is a CHAINED COMMAND and $?5$
  5713.  
  5714.           Step #2:   Here is a CHAINED COMMAND and ANOTHER $?5$
  5715.                      EMBEDDED $?4$ VALUE
  5716.  
  5717.           Step #3:   Here is a CHAINED COMMAND and ANOTHER ANOTHER 
  5718.                      $?5$ EMBEDDED $?4$ VALUE EMBEDDED (hello) VALUE
  5719.  
  5720.                <end of processing>
  5721.  
  5722.  
  5723.    EXAMPLE 4
  5724.    ---------
  5725.  
  5726.           [5:]HELLO
  5727.  
  5728.           [3:]$?5$ $?$ WORLD
  5729.  
  5730.           [4:]print("$?$")^m
  5731.  
  5732.           [344](silly)
  5733.  
  5734.      This would result in:
  5735.  
  5736.           print("print("HELLO (silly) WORLD")^m")^m
  5737.  
  5738.  
  5739. Example #1 shows a situation with a single chaining operation and a
  5740. single embedding operation done at the same time.  You can see how
  5741. the final host command is in relation to the data fed into the
  5742. templates at different points.
  5743.  
  5744. Example #2 shows a more complex situation where multiple levels of
  5745. template chaining are going on while embedding is also being used.
  5746.  
  5747. Example #3 is somewhat different though.  Why weren't the embedded
  5748. template codes expanded at the lowest level of template #5?  If you
  5749. look closely at template #5, it has an insertion code instructing the
  5750. system to insert template #5 (itself) in the middle of the template. 
  5751. This is legal, but only because an embedded template inside an
  5752. embedded template cannot have any more embedding performed on it.  In
  5753. other words, you are allowed up to two levels of embedded templates,
  5754. but the lowest level (2nd) cannot have any insertion codes, text
  5755. variables, control characters or pick-list definitions in it - if it
  5756. does, they will be treated as "raw" text instead of host command
  5757. directives.
  5758.  
  5759. Example #4 shows a more involved Template Chaining operation in which
  5760. the same template is chained to more than once in a given operation. 
  5761. This is allowable for extra flexibility, although in the real world
  5762. will probably not be used much.
  5763.  
  5764.  
  5765.  
  5766.  
  5767. TEMPLATES, TEXT VARIABLES, PICK LISTS AND CONTROL CHARACTERS
  5768. ------------------------------------------------------------
  5769. Now that we have thouroughly discussed templates, we come upon
  5770. another subject - that of text variables, pop-up pick lists, and
  5771. control characters.  In any template definition or host command, you
  5772. can have text variables, pick lists or control characters anywhere.
  5773. This gives you the ability to do a great many things.
  5774.  
  5775. You can freely use text variables, control characters or pick lists
  5776. anywhere in a Direct Host Command, in a template chains and embedded
  5777. templates.  There is nothing unusual about text variables, pop-up
  5778. pick lists or control characters when they're used in template chains
  5779. or Direct Host Commands.  They do get a bit odd though in how they
  5780. interact with Embedded Templates - but only if you have an embedded
  5781. template within an embedded template.
  5782.  
  5783. Recall from a previous discussion about embedded templates within
  5784. embedded templates.  At the lowest level of the embedding, there is
  5785. no processing done on the string of text.  This is to prevent endless
  5786. loops and combinatorial explosion of data and CPU time.  Text
  5787. Variables, pick lists and control characters WILL be processed at the
  5788. first level of an embedded template, but not at the second level.
  5789.  
  5790. Here are some examples that better illustrate text variables:
  5791.  
  5792.  
  5793.      EXAMPLE 1
  5794.      ---------
  5795.  
  5796.           [3:]The date is $DATE$ ... $?$
  5797.  
  5798.           [3]HELLO
  5799.  
  5800.        Results in:
  5801.  
  5802.           The date is 07/18/93 ... HELLO
  5803.  
  5804.  
  5805.  
  5806.      EXAMPLE 2
  5807.      ---------
  5808.  
  5809.           [3:]The date is $DATE$
  5810.  
  5811.           HELLO THERE, $?3$
  5812.  
  5813.        Results in:
  5814.  
  5815.           HELLO THERE, The date is 07/18/93
  5816.  
  5817.  
  5818.  
  5819.      EXAMPLE 3
  5820.      ---------
  5821.  
  5822.           [2:]The time is $TIME$^m
  5823.           [3:]The date is $DATE$^m
  5824.  
  5825.           HELLO THERE^m$?3$$?4$
  5826.  
  5827.        Results in:
  5828.  
  5829.           HELLO THERE
  5830.           The date is 07/18/93
  5831.           The time is 03:43:32
  5832.  
  5833.  
  5834.  
  5835.      EXAMPLE 4
  5836.      ---------
  5837.  
  5838.           [1:]The day is $DOW$^m
  5839.  
  5840.           [2:]The time is $TIME$^m
  5841.           [3:]The date is $DATE$^m$?1$^m
  5842.  
  5843.           HELLO THERE^m($?3$)($?4$)($?1$)
  5844.  
  5845.        Results in:
  5846.  
  5847.           HELLO THERE
  5848.           (The date is 07/18/93)
  5849.           The day is $DOW$^m
  5850.           (The time is 03:43:32)
  5851.           (The day is Sunday)
  5852.  
  5853.        Notice how the $?1$ embedded template used in template #3 does
  5854.        not get processed - it is just inserted raw.
  5855.  
  5856.  
  5857.  
  5858. PROCESSING OF TEMPLATES
  5859. -----------------------
  5860. As stated previously, template definitions may contain text 
  5861. variables, pick lists, control characters, and template insertion
  5862. codes.  When do these special "directives" get processed?  The answer
  5863. is when the template gets USED, not when it becomes ACTIVE!  To
  5864. better illustrate this, let's look at a simple example.
  5865.  
  5866. Let's say you have three radio buttons (group #2) on the screen and
  5867. another button (group #0) which uses the template for the radio
  5868. button group 3.  Here's the host command definitions for each of
  5869. these four buttons:
  5870.  
  5871.  
  5872.      Group #2 - Radio Button Group
  5873.      -----------------------------
  5874.  
  5875.           Button #1:  [2:]It's a pretty day at $TIME$
  5876.           Button #2:  [2:]It's a rainy day at $TIME$
  5877.           Button #3:  [2:]It's a hazy day at $TIME$
  5878.  
  5879.      Group #0 - Ordinary button group
  5880.      --------------------------------
  5881.  
  5882.           Button #4:  Today's forecast:^m$?2$
  5883.  
  5884.  
  5885. Now, let's say that none of the radio buttons are drawn as "selected"
  5886. for starters.  At 11:45:03 in the morning, the user clicks on button
  5887. #2 indicating it's a rainy day.  The active template for group #2
  5888. would be defined as:
  5889.  
  5890.           It's a rainy day at $TIME$
  5891.  
  5892. At 11:46:37 he clicks on the Forecast button.  What would be the host
  5893. command sent to the BBS in this example?  It would be:
  5894.  
  5895.           Today's forecast:
  5896.           It's a rainy day at 11:46:37
  5897.  
  5898. Notice that the time that is inserted in place of $TIME$ is the time
  5899. that the user clicked on the Forecast button, NOT the time he clicked
  5900. on the "rainy day" button which activated the proper template.  This
  5901. illustrates that text variables, pick lists, and control characters
  5902. are not "processed" until they are referenced (used) by some other
  5903. button or template in an active Host Command situation.
  5904.  
  5905.  
  5906.  
  5907. COMMAND BLOCKS - SEGMENTING A HOST COMMAND 
  5908. ------------------------------------------
  5909. Near the beginning of our discussion of templates we spoke about
  5910. Direct Host Commands, Template Definitions and Template Execution.
  5911. You have seen how to define templates with a template definition
  5912. command like [3:]HELLO, and how to execute templates by either
  5913. Chaining (eg, "[3]WORLD"), or by using Embedded Templates 
  5914. (eg, "$?3$ WORLD").
  5915.  
  5916. Now, remember that we spoke about how a single Host Command can be
  5917. segmented into multiple "Command Blocks" by separating them with the
  5918. delimiter "[]".  An example of this might be:
  5919.  
  5920.      HELLO^m[]WORLD^m
  5921.  
  5922. This would transmit the following to the BBS:
  5923.  
  5924.      HELLO<cr>
  5925.      WORLD<cr>
  5926.  
  5927. Realistically, you wouldn't use such an overly simple example like
  5928. this, but would use the following instead:
  5929.  
  5930.      HELLO^mWORLD^m
  5931.  
  5932. This would produce the same result.  But it doesn't illustrate the
  5933. purpose of Command Blocks.  Here's a real-world example of a host
  5934. command broken down into several command blocks:
  5935.  
  5936.   [3:]Template Definition[4]Template chaining[]BBS TEXT
  5937.  
  5938. If you look carefully at the above host command, three distinct
  5939. things are happening.  First, template #3 is defined with the text
  5940. "Template Definition".  Secondly, the phrase "Template chaining"
  5941. is chained (fed) into template #4 (whatever that one is) and the
  5942. final result of the chaining operation is sent to the BBS.  Finally,
  5943. the last command block is processed which happens to be a Direct Host
  5944. Command, so the text "BBS TEXT" will be transmitted to the Host as
  5945. well.
  5946.  
  5947. If a host command doesn't have one of the command block delimiters
  5948. like a template definition (eg, "[3:]"), or a template chain
  5949. directive (eg, "[3]"), or a Direct Host Command Directive (eg, "[]"),
  5950. then the Host Command is, by default, considered to be a Direct Host
  5951. Command.  The following are all considered Direct Host Commands and
  5952. they all do the exact same thing:
  5953.  
  5954.      HELLO^mWORLD^m
  5955.      HELLO^m[]WORLD^m
  5956.      []HELLO^mWORLD^m
  5957.      []HELLO^m[]WORLD^m
  5958.  
  5959. Here are some more examples of Command Blocks using the previous
  5960. example as a foundation, but this time we throw in another command
  5961. block.  Again, all four of these examples do the exact same things:
  5962.  
  5963.      HELLO^mWORLD^m[3:]Template Definition
  5964.      HELLO^m[]WORLD^m[3:]Template Definition
  5965.      []HELLO^mWORLD^m[3:]Template Definition
  5966.      []HELLO^m[]WORLD^m[3:]Template Definition
  5967.  
  5968.  
  5969.  
  5970. COMMAND BLOCKS, RADIO BUTTONS AND CHECK BOX BUTTONS
  5971. ---------------------------------------------------
  5972. If you recall from our earlier discussions about Radio Buttons and
  5973. Check Box Buttons, the templates definitions are activated based upon
  5974. a Button being activated.  If you think about Command Blocks though,
  5975. you might be inclined to think that figuring out which template
  5976. definition block of a command block to activate might get insane.  It
  5977. could!  Look at the following set of three Radio Button definitions:
  5978.  
  5979.      Button #1:  [3:]Hello world[3:]This is Pluto
  5980.      Button #2:  [3:]Hello world[3:]This is Saturn
  5981.      Button #3:  [3:]Hello world[3:]This is Jupiter
  5982.  
  5983. What happens if button #2 is clicked, thus activating that template? 
  5984. What template command block is used to create the final, active
  5985. template?  The answer is the last one!  The text that becomes the
  5986. actual active template for template #3 would be this:
  5987.  
  5988.      This is Saturn
  5989.  
  5990. If a Host Command references this template as in the following
  5991. example, you will see that the secondary template definition is
  5992. the one that is actually in use:
  5993.  
  5994.      I'm a martian singing in the rain^m$?3$
  5995.  
  5996. Resulting in:
  5997.  
  5998.      I'm a martian singing in the rain
  5999.      This is Saturn
  6000.  
  6001. In short, Command Blocks are processed in all situations, and if a
  6002. discrepency exists where two or more template definitions in the same
  6003. Host String correspond to the same template group, the last
  6004. definition is the one that becomes active.  This applies even if you
  6005. are dealing with Check Box buttons.  In the above example of the
  6006. martian, if Buttons #1, 2 and 3 were Check Box Buttons instead, the
  6007. "Hello World" template definitions would still be lost and would NOT
  6008. get concatenated together to create the final Host Command.  If
  6009. buttons #1 and #3 are clicked, then template #3 would be:
  6010.  
  6011.      This is PlutoThis is Jupiter
  6012.  
  6013. It would NOT be:
  6014.  
  6015.      Hello worldThis is PlutoHello worldThis is Jupiter
  6016.  
  6017.  
  6018.  
  6019. CONTROL CHARACTERS
  6020. ------------------
  6021. Not all BBS'es will allow you to use control characters on their
  6022. Service.  Regardless of that, the capability to send any Control
  6023. Character exists for your Host Commands.  The most commonly used
  6024. Control Characters are:
  6025.  
  6026.    INDIVIDUAL CONTROL CHARACTERS         SPECIAL KEYSTROKES
  6027.    ===========================================================
  6028.    ^@ ... Null (ASCII 0)                 ^[[A ... Up Arrow
  6029.    ^G ... Beep                           ^[[B ... Down Arrow
  6030.    ^L ... Clear Screen (Top of Form)     ^[[C ... Right Arrow
  6031.    ^M ... Carriage Return                ^[[D ... Left Arrow
  6032.    ^C ... Break (sometimes)              ^[[H ... Home Key
  6033.    ^H ... Backspace                      ^[[K ... End Key
  6034.    ^[ ... Escape character               ^[[L ... Control Home
  6035.    ^S ... Pause data transmission        
  6036.    ^Q ... Resume data transmission
  6037.  
  6038. Some hosts use the ^ (caret) for their own purposes.  In these
  6039. cases, you can use the ` (backquote) character instead of the
  6040. caret.  Some systems allow you to specify the caret symbol as
  6041. two carets (^^).  Consult your Host Software documentation to
  6042. determine the best method for your needs.
  6043.  
  6044. NOTE:  RIPterm uses ^ or ` and a character to represent a control
  6045.        character.  IT IS NOT A CONTROL CHARACTER BY ITSELF, IT
  6046.        IS TRANSLATED BY RIPterm.  In other words, ^M does not send
  6047.        a ^ and then an M, it sends a carriage return (ASCII 13).
  6048.        Likewise, RIPscrip commands like Query do not use an ^[, an
  6049.        actual escape character (ASCII 27) is used.
  6050.  
  6051.  
  6052.  
  6053. TEXT VARIABLES
  6054. --------------
  6055. A special feature of RIPterm allows it to understand what a Text
  6056. Variable is.  A text variable is a piece of text that both RIPaint
  6057. and RIPterm know something about.  For example, the Text Variable
  6058. $DATE$ is known to represent the current Date on your PC.  The host
  6059. may ask your system what the values of one or more of these variables
  6060. are, and if your terminal knows these particular Text Variables, it
  6061. will tell the host.
  6062.  
  6063. There are three types of Text Variables.
  6064.  
  6065. -- Built-In Text Variables that RIPscrip products will ALWAYS
  6066.    know about.  These include Text Variables like date and time
  6067.    that return a value
  6068.  
  6069. -- Another type of built-in Text Variable are Active Text
  6070.    Variables, which perform an action, but return nothing to
  6071.    the host.  These include turning the status bar on/off,
  6072.    clearing the graphics screen, and playing some simple
  6073.    sounds, and many more.
  6074.  
  6075. -- Then there are also User Text Variables that can contain
  6076.    a variety of information depending on what the user
  6077.    entered at the time the variable was created.  For
  6078.    example, the host might ask you what the contents of the
  6079.    $FULL_NAME$ variable is, and if RIPterm doesn't know, it
  6080.    could pop-up a field on the screen and ask you about it.
  6081.    From then on, RIPterm will remember that piece of
  6082.    information for the next time it is needed by a host.
  6083.  
  6084. You may use either the pre-defined Text Variables, or the User Text
  6085. Variables at any place that allows Text Variables.
  6086.  
  6087.  
  6088.  
  6089. LOCAL RIPscrip FILE PLAYBACK
  6090. ----------------------------
  6091. You can re-play a .RIP file that you have locally on your hard disk
  6092. from anyplace that allows text variables.  The format of the variable
  6093. is somewhat different than user variables, or pre-defined text
  6094. variables.  After the initial dollar sign ($), enter the greater-than
  6095. symbol (>) followed by the filename (with or without the .RIP
  6096. extension), then ending in another dollar sign ($).  Several examples
  6097. of this are as follows:
  6098.  
  6099.          $>MYFILE.RIP$
  6100.          $>FILE1$
  6101.          $>FILE1.RIP$$>FILE2.RIP$$>FILE3$
  6102.  
  6103. Note in the last example, a file extension other than .RIP was used.
  6104. You are not limited to playing back local .RIP files.  In fact, you
  6105. can play-back any file you want.  You could load any simple text
  6106. file, ANSI picture image, or other such thing.  When loaded, the data
  6107. is not sent to the host; it is strictly echoed on your local screen.
  6108. If the file is a .RIP file, it will replay any graphics that were in
  6109. the file and if any Mouse Regions are defined, it will create those
  6110. fields for you as well, thus allowing you to pop-up dialog screens or
  6111. other such things that are not built-in to RIPterm normally.
  6112.  
  6113. Each "local RIP playback" variable you enter will search for the .RIP
  6114. file in the current host's icon directory.  If it cannot find the
  6115. file in that directory, it will check the ICONS\ directory.
  6116.  
  6117. When Local RIPscrip File Playback is chosen, the file is not played
  6118. back immediately.  Whatever operation is being processed (like a host
  6119. command being sent to the BBS, etc) will be completed.  After the
  6120. completion of the command in question, the RIPscrip file is played
  6121. back locally.  An internal Queue of files is stored in memory in
  6122. RIPterm.  Each time it gets a Local RIP file playback command, it
  6123. adds the filename to the queue.  When the current operation is
  6124. completed, the queue is flushed by playing back all of the files in
  6125. the queue in the order that they were received.
  6126.  
  6127.  
  6128.  
  6129. POP-UP PICK LISTS
  6130. -----------------
  6131. Any place that you can use a Text Variable (Queries, Button and Mouse
  6132. Field return strings, and Keystroke Macros), you can take advantage of
  6133. a unique feature of RIPscrip - Pop-Up Pick Lists.  A Pop-Up Pick List
  6134. is simply a list that pops up allowing you to choose from one of
  6135. several available values.  Whichever entry in the list you choose
  6136. will insert it's associated command in the Host Command returned back
  6137. to your host.
  6138.  
  6139. A list is created by putting the special list instructions inside two
  6140. sets of parenthesis like this: (( and )).  The list consists of an
  6141. optional question followed by two colons (::), followed by one or
  6142. more list entries.  For example, ((Send Email
  6143. to?::Sysop,Cosysop,Joe)) says to pop-up a list asking you "Send Email
  6144. to?", giving you the choices of "Sysop", "Cosysop", and "Joe".
  6145.  
  6146. By default, if you press ESC instead of picking an entry in the list,
  6147. then nothing will be inserted into the text of your Command. You can
  6148. indicate that the user must pick an entry by putting an asterisk (*)
  6149. at the beginning of the question.  For example, ((*Send Mail
  6150. to?::Sysop,Joe)).  This would make it so that the user must choose
  6151. either Sysop or Joe.
  6152.  
  6153. In the previous examples, Sysop and Joe are the text responses that
  6154. are inserted into your Host Command.  These commands are also the
  6155. same things that are displayed in the listing.  If you want to use
  6156. something else in the listing instead of the return text, you can.
  6157. When you make the list entry, add an @description to the end of it.
  6158. For example:
  6159.  
  6160.      ((Send Mail To?::Sysop@Head Honcho,Cosysop,Joe))
  6161.  
  6162. ...would display a pop-up pick list of Head Honcho, Cosysop, and Joe.
  6163.  
  6164. One final feature of Pop-Up Pick Lists allows you to specify a hotkey
  6165. for each entry in the list.  For example, if you wanted the first
  6166. character of each entry to be highlighted (thus allowing you to
  6167. select that character to activate the entry), simply put a tilde (~)
  6168. or an underline (_) before and after the keystroke.  For example
  6169. "_S_ysop" would highlight the "S" in "Sysop" appearing like this:
  6170.  
  6171.                        Sysop
  6172.  
  6173. You can highlight more than one character, but only the first one will
  6174. be the active hotkey.  If you omit the second tilde or underline,
  6175. then the remainder of the description will be highlighted.
  6176.  
  6177. NOTE:  If you use a tilde or an underline in the Text Response (not
  6178.        the description), then those characters are inserted into
  6179.        your Host Command when it is transmitted to the host.  You
  6180.        probably don't want to do this.  Recommendation: only use
  6181.        hotkey features on list entries where you specify a
  6182.        description!
  6183.  
  6184. If you do not specify a question, then the list default to the
  6185. question:
  6186.  
  6187.                Choose one of the following:
  6188.  
  6189. You may specify up to twenty entries for any one list.  In RIPterm 
  6190. version 1.52 and earlier, the total length of a pick list was 256  
  6191. bytes.  In version 1.53 and later, this limit has been increased to
  6192. 1024 bytes.                                                        
  6193.  
  6194. Some characters have special significance in the RIPscrip language.
  6195. These characters are ! (exclamation mark, or for you Unix-heads,
  6196. bang), \ (backslash), and | (vertical bar).  To use these characters
  6197. in a Text Response, they must be preceded by a backslash (! becomes
  6198. \!, \ becomes \\, and | becomes \|).  RIPaint automatically adds
  6199. these when creating Text Responses.  You need to be aware of this
  6200. only if you are editing RIPscrip files with a text editor.  The _
  6201. (underline) and ~ (tilde) characters used to indicate the hotkey in a
  6202. Text Response are not able to be preceded by a backslash to be used
  6203. by themselves.  They will be returned to the host if they exist in a
  6204. Text Response (not in the description), however everything after the
  6205. underline or tilde will be underlined, and the first character will
  6206. be considered the hotkey.
  6207.  
  6208.   Examples:
  6209.  
  6210.      ((Send E-Mail to?::Sysop,Joe,Mike))
  6211.      ((*Send E-Mail to?::Sysop@The Head Honcho,Joe,Mike@My Brother))
  6212.      ((::Sysop@_T_he Head Honcho,Joe,Mike@My _B_rother))
  6213.  
  6214.  
  6215.  
  6216. WHAT CAN GO WHERE?
  6217. ------------------
  6218. With all this talk about Templates, Text Variables, Local RIP file
  6219. playback, pop-up pick lists and control characters, you might be
  6220. interested in knowing what can be used where in the RIPscrip
  6221. language.  It has already been stated that Templates can be used only
  6222. in Button Host Commands.  Text Variables, Local RIP file playback,
  6223. pop-up lists and control characters can be used in several places
  6224. though.  The places that these commands can be used and not used are
  6225. listed in the following chart:
  6226.  
  6227.                     +-----------------------------------+
  6228.                     |  T  | D V |   T |  P  |  C  |  L  |
  6229.                     |  E  | A A | A E |  I  |  T  |  O  |
  6230.                     |  M  | T R | C X |  C  |  R  |  C  |
  6231.                     |  P  | A I | T T |  K  |  L  |  A  |
  6232.                     |  L  |   A | I   |     |     |  L  |
  6233.                     |  A  | T B | V V |  L  |  C  |     |
  6234.                     |  T  | E L | E A |  I  |  H  |  R  |
  6235.                     |  E  | X E |   R |  S  |  A  |  I  |
  6236.                     |  S  | T S |   S |  T  |  R  |  P  |
  6237.                     |-----------------------------------|
  6238.                     |     |     |     |     |     |     |
  6239. Button Host Commands|  Y  |  Y  |  Y  |  Y  |  Y  |  Y  | 
  6240.                     |     |     |     |     |     |     | Host
  6241. Simple Mouse Fields |  N  |  Y  |  Y  |  Y  |  Y  |  Y  | Related
  6242.                     |     |     |     |     |     |     | Commands
  6243. Query Command       |  N  |  Y  |  Y  |  Y  |  Y  |  Y  |
  6244.                     |     |     |     |     |     |     |
  6245.                     |-----------------------------------|
  6246.                     |     |     |     |     |     |     |
  6247. Button Labels       |  N  |  Y  |  N  |  N  |  N  |  N  |
  6248.                     |     |     |     |     |     |     | Text Output
  6249. RIP_TEXT_XY         |  N  |  Y  |  N  |  N  |  N  |  N  | Related
  6250.                     |     |     |     |     |     |     | Commands
  6251. RIP_TEXT            |  N  |  Y  |  N  |  N  |  N  |  N  |
  6252.                     |     |     |     |     |     |     |
  6253.                     +-----------------------------------+
  6254.  
  6255.  
  6256.  
  6257. THINGS TO TAKE SPECIAL CARE WITH
  6258. --------------------------------
  6259. Special care must be taken when executing Host Commands or Query
  6260. commands that contain local RIP file playback or that contain active
  6261. text variables.  Either of these operations could instruct RIPterm to
  6262. destroy all Mouse Fields by either performing a RIP_RESET_WINDOWS
  6263. command ($RESET$), a RIP_KILL_MOUSE_FIELDS command ($MKILL$), a
  6264. restore mouse fields text variable ($RMF$) or other such things.
  6265.  
  6266. If a situation like this happens, care should be taken to preserve
  6267. currently processed Host Buffer.  If it is a mouse field's host
  6268. command that is being processed, you wouldn't want your application
  6269. destroying the very buffer that you're processing before you're done
  6270. processing it, would you?  In the case of RIPterm, we do a sub-string
  6271. search on the Host buffer before any processing is done.  We search
  6272. for the following strings:
  6273.  
  6274.      $RMF$    ... Restore Mouse Fields
  6275.      $>       ... Beginning segment of a Local RIP playback command
  6276.      $APP     ... Instruction to execute an external application
  6277.      $RESET$  ... Performs a RIP_RESET_WINDOWS command
  6278.      $MKILL$  ... Destroys the contents of the internal mouse table
  6279.  
  6280. If any one of the above strings are found, RIPterm will physically
  6281. back-up the Host buffer into another location - one that won't be
  6282. destroyed by the execution of the above commands.  The processing of
  6283. the Host buffer is then done on the new buffer, not the actual
  6284. buffer.  In this way, the application can destroy the mouse table to
  6285. its heart's content but the processing of the buffer will not be
  6286. affected.
  6287.